RLAMA - User Guide

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

• Installation
• Available Commands
  • rag - Create a RAG system
  • run - Use a RAG system
  • list - List RAG systems
  • delete - Delete a RAG system
  • update - Update RLAMA
  • version - Display version
• Uninstallation
• Supported Document Formats
• Troubleshooting

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:

rlama/
├── cmd/                  # CLI commands (using Cobra)
│   ├── root.go           # Base command
│   ├── rag.go            # Create RAG systems
│   ├── run.go            # Query RAG systems
│   └── ...
├── internal/
│   ├── client/           # External API clients
│   │   └── ollama_client.go # Ollama API integration
│   ├── domain/           # Core domain models
│   │   ├── rag.go        # RAG system entity
│   │   └── document.go   # Document entity
│   ├── repository/       # Data persistence
│   │   └── rag_repository.go # Handles saving/loading RAGs
│   └── service/          # Business logic
│       ├── rag_service.go      # RAG operations
│       ├── document_loader.go  # Document processing
│       └── embedding_service.go # Vector embeddings
└── pkg/                  # Shared utilities
    └── vector/           # Vector operations

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     │<────│ Vector Store│
│  Response   │     │  Search     │     │ (RAG System)│
└─────────────┘     └─────────────┘     └─────────────┘
       ▲                   │
       │                   ▼
┌─────────────┐     ┌─────────────┐
│   Ollama    │<────│   Context   │
│    LLM      │     │  Building   │
└─────────────┘     └─────────────┘

RLAMA is designed to be lightweight and portable, focusing on providing RAG capabilities with minimal dependencies. The entire system runs locally, with the only external dependency being Ollama for LLM capabilities.

Available Commands

You can get help on all commands by using:

rlama --help

Global Flags

These flags can be used with any command:

--host string   Ollama host (default: localhost)
--port string   Ollama port (default: 11434)

rag - Create a RAG system

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

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

Parameters:

• model: Name of the Ollama model to use (e.g., llama3, mistral, gemma).
• rag-name: Unique name to identify your RAG system.
• folder-path: Path to the folder containing your documents.

Example:

rlama rag llama3 documentation ./docs

run - Use a RAG system

Starts an interactive session to interact with an existing RAG system.

rlama run [rag-name]

Parameters:

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

Example:

rlama run documentation
> How do I install the project?
> What are the main features?
> exit

list - List RAG systems

Displays a list of all available RAG systems.

rlama list

delete - Delete a RAG system

Permanently deletes a RAG system and all its indexed documents.

rlama delete [rag-name] [--force/-f]

Parameters:

• rag-name: Name of the RAG system to delete.
• --force or -f: (Optional) Delete without asking for confirmation.

Example:

rlama delete old-project

Or to delete without confirmation:

rlama delete old-project --force

update - Update RLAMA

Checks if a new version of RLAMA is available and installs it.

rlama update [--force/-f]

Options:

• --force or -f: (Optional) Update without asking for confirmation.

version - Display version

Displays the current version of RLAMA.

rlama --version

or

rlama -v

Uninstallation

To uninstall RLAMA:

Removing the binary

If you installed via go install:

rlama uninstall

Removing data

RLAMA stores its data in ~/.rlama. To remove it:

rm -rf ~/.rlama

Supported Document Formats

RLAMA supports many file formats:

• Text: .txt, .md, .html, .json, .csv, .yaml, .yml, .xml
• Code: .go, .py, .js, .java, .c, .cpp, .h, .rb, .php, .rs, .swift, .kt
• Documents: .pdf, .docx, .doc, .rtf, .odt, .pptx, .ppt, .xlsx, .xls, .epub

Installing dependencies via install_deps.sh is recommended to improve support for certain formats.

Troubleshooting

Ollama is not accessible

If you encounter connection errors to Ollama:

1. Check that Ollama is running.
2. By default, Ollama must be accessible at http://localhost:11434 or the host and port specified by the OLLAMA_HOST environment variable.
3. If your Ollama instance is running on a different host or port, use the --host and --port flags:

   rlama --host 192.168.1.100 --port 8000 list
   rlama --host my-ollama-server --port 11434 run my-rag
4. Check Ollama logs for potential errors.

Text extraction issues

If you encounter problems with certain formats:

1. Install dependencies via ./scripts/install_deps.sh.
2. Verify that your system has the required tools (pdftotext, tesseract, etc.).

The RAG doesn't find relevant information

If the answers are not relevant:

1. Check that the documents are properly indexed with rlama list.
2. Make sure the content of the documents is properly extracted.
3. Try rephrasing your question more precisely.

Other issues

For any other issues, please open an issue on the GitHub repository providing:

1. The exact command used.
2. The complete output of the command.
3. Your operating system and architecture.
4. The RLAMA version (rlama --version).

Configuring Ollama Connection

RLAMA provides multiple ways to connect to your Ollama instance:

1. Command-line flags (highest priority):

   rlama --host 192.168.1.100 --port 8080 run my-rag

2. Environment variable:

   # Format: "host:port" or just "host"
   export OLLAMA_HOST=remote-server:8080
   rlama run my-rag

3. Default values (used if no other method is specified):

   • Host: localhost
   • Port: 11434

The precedence order is: command-line flags > environment variable > default values.