Getting Started¶
Prerequisites¶
Before using Ragdoll, ensure you have:
Setting Up Ollama¶
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Pull the required models
ollama pull nomic-embed-text # embedding model
ollama pull gemma4:12b # chat model (Linux / Windows with NVIDIA or Apple Silicon)
# Or for deep technical coding:
# ollama pull qwen3.8:27b # 27B model for complex AST reasoning
# Verify models are available
ollama list
Note
gemma4:12b requires ~7.6 GB of VRAM, fitting comfortably on 8 GB, 12 GB, and 16 GB GPUs or unified memory Macs.
Tip
Apple Silicon (M1/M2/M3/M4) Optimization with -mlx Tags:
If you are running Ragdoll on an Apple Silicon Mac, consider pulling models with the -mlx tag (e.g. qwen3.8:27b-mlx, gemma4:12b-mlx).
Architecture: Standard Ollama models use the GGUF format powered by
llama.cpp. The-mlxvariants run natively via Apple’s MLX machine learning framework, designed exclusively for Apple Silicon.Performance: MLX models directly leverage Apple Silicon’s unified memory architecture and Metal GPU optimizations, delivering substantially faster token generation (eval rate), lower prompt-processing latency, and improved memory throughput.
Platform Compatibility:
-mlxmodels run exclusively on Apple Silicon macOS (M1/M2/M3/M4). (For Linux or Windows systems with NVIDIA GPUs, use standard GGUF models).
For heavy ingestion workloads and concurrent chat tuning on Apple Silicon and Linux, see Performance & Concurrency Tuning.
Installation¶
# Clone the repository
git clone <repo-url> ragdoll
cd ragdoll
# Install with pixi
pixi install
# Verify the installation
pixi run ragdoll --version
pixi run ragdoll --help
pixi run ragdoll status
Initial Configuration¶
Create your user-level configuration file:
mkdir -p ~/.ragdoll && chmod 700 ~/.ragdoll
cat > ~/.ragdoll/config.toml << 'EOF'
# ==========================================
# 1. Global / Top-Level Settings
# (Must be at the very top of the file)
# ==========================================
chat_model = "gemma4:12b"
embed_model = "nomic-embed-text"
chunk_size = 1000
# ==========================================
# 2. Jira Server Configurations
# (Nested dictionary blocks go below globals)
# ==========================================
[jira_servers.primary]
url = "https://primary-jira.example.com"
user = "your.username"
token = "YOUR_PERSONAL_ACCESS_TOKEN"
auth_method = "pat"
projects = ["CORE", "BACKEND"]
[jira_servers.secondary]
url = "https://secondary-jira.example.com"
user = "your.username"
token = "YOUR_PERSONAL_ACCESS_TOKEN"
auth_method = "pat"
projects = ["EXTERNAL", "TOOLS"]
# ==========================================
# 3. Bitbucket Server Configurations
# ==========================================
[bitbucket_servers.internal]
url = "https://bitbucket.example.com"
user = "your.username"
token = "YOUR_HTTP_ACCESS_TOKEN"
auth_method = "pat"
# ==========================================
# 4. GitHub Configurations
# ==========================================
github_token = "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
github_default_owner = "myorg"
github_repos = ["myorg/repo1", "myorg/repo2"]
[github_servers.enterprise]
url = "https://github.internal.mycompany.com/api/v3"
token = "YOUR_ENTERPRISE_TOKEN"
repos = ["internal-org/service"]
EOF
chmod 600 ~/.ragdoll/config.toml
Important
Protect your config file with chmod 600 — it contains your JIRA token.
First Ingestion¶
# Ingest some PDF documentation
pixi run ragdoll ingest pdf ./path/to/docs/
# Ingest recent JIRA tickets
pixi run ragdoll ingest jira --jql "project = MYPROJ AND updated >= -30d"
# Ingest GitHub issues and PR discussions
pixi run ragdoll ingest github myorg myrepo --state all
# Ingest a Python codebase
pixi run ragdoll ingest code ./src/
# Check what was indexed
pixi run ragdoll status
First Query¶
# Search
pixi run ragdoll search "how does the data processing pipeline work?"
# Summarize
pixi run ragdoll summarize "known performance issues"
# Interactive chat
pixi run ragdoll chat