pedicab 0.3.1 → 0.3.3

data/Gemfile.lock

@@ -1,42 +1,28 @@
 PATH
   remote: .
   specs:
-    pedicab (0.3.0)
+    pedicab (0.3.2)
       benchmark
-      eqn
-      httparty
+      carpet
       json
-      nokogiri
       open3
-      redcarpet
 
 GEM
   remote: https://rubygems.org/
   specs:
     benchmark (0.5.0)
-    bigdecimal (3.3.1)
-    csv (3.3.5)
-    eqn (1.6.5)
-      treetop (>= 1.2.0)
-    httparty (0.23.2)
-      csv
-      mini_mime (>= 1.0.0)
-      multi_xml (>= 0.5.2)
+    carpet (0.1.0)
+      pry
+      redcarpet
+    coderay (1.1.3)
     json (2.16.0)
-    mini_mime (1.1.5)
-    mini_portile2 (2.8.9)
-    multi_xml (0.7.1)
-      bigdecimal (~> 3.1)
-    nokogiri (1.18.10)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
+    method_source (1.1.0)
     open3 (0.2.1)
-    polyglot (0.3.5)
-    racc (1.8.1)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rake (13.0.6)
     redcarpet (3.6.1)
-    treetop (1.6.18)
-      polyglot (~> 0.3)
 
 PLATFORMS
   x86_64-linux

data/INSTALLATION.md

@@ -0,0 +1,652 @@
+# Installation and Setup Guide
+
+## Table of Contents
+
+1. [System Requirements](#system-requirements)
+2. [Installation](#installation)
+3. [Model Setup](#model-setup)
+4. [Configuration](#configuration)
+5. [Verification](#verification)
+6. [Troubleshooting](#troubleshooting)
+7. [Platform-Specific Notes](#platform-specific-notes)
+
+---
+
+## System Requirements
+
+### Minimum Requirements
+
+- **Ruby**: >= 2.6.0
+- **Python**: >= 3.7
+- **RAM**: 4GB minimum (8GB+ recommended for larger models)
+- **Storage**: 2GB free space for models + application
+- **OS**: Linux, macOS, or Windows (with WSL2)
+
+### Recommended Requirements
+
+- **Ruby**: >= 3.0.0
+- **Python**: >= 3.9
+- **RAM**: 16GB+ for optimal performance
+- **GPU**: CUDA-compatible GPU (optional, for acceleration)
+- **Storage**: 10GB+ free space
+
+### Software Dependencies
+
+#### Ruby Gems
+- `benchmark` (built-in)
+- `open3` (built-in)
+- `json` (built-in)
+- `erb` (built-in)
+- `carpet`
+
+#### Python Packages
+- `llama-cpp-python`
+
+---
+
+## Installation
+
+### Option 1: Install from RubyGems (Recommended)
+
+```bash
+# Install the gem
+gem install pedicab
+
+# Install Python dependency
+pip install llama-cpp-python
+```
+
+### Option 2: Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/xorgnak/pedicab.git
+cd pedicab
+
+# Install the gem
+bundle install
+rake install
+
+# Install Python dependencies
+pip install llama-cpp-python
+```
+
+### Option 3: Development Setup
+
+```bash
+# Clone for development
+git clone https://github.com/xorgnak/pedicab.git
+cd pedicab
+
+# Install development dependencies
+bundle install
+
+# Install Python dependencies
+pip install llama-cpp-python
+
+# Run tests (if available)
+rake test
+```
+
+---
+
+## Model Setup
+
+### Model Format Requirements
+
+Pedicab uses **GGUF** (GPT-Generated Unified Format) models. These are:
+- Quantized models optimized for CPU inference
+- Compatible with llama.cpp and llama-cpp-python
+- Single file containing the complete model
+
+### Recommended Models
+
+#### Small Models (1-3GB)
+- **Qwen2.5-1.5B-Instruct-Q4_K_M.gguf** - Good balance of speed and quality
+- **Phi-3-mini-4k-instruct-q4.gguf** - Excellent for general tasks
+- **Gemma-2B-it-Q4_K_M.gguf** - Google's efficient model
+
+#### Medium Models (4-7GB)
+- **Qwen2.5-7B-Instruct-Q4_K_M.gguf** - High quality, reasonably fast
+- **Llama-3.1-8B-Instruct-Q4_K_M.gguf** - Very capable model
+- **Mistral-7B-Instruct-v0.2-Q4_K_M.gguf** - Popular and reliable
+
+#### Large Models (8GB+)
+- **Qwen2.5-14B-Instruct-Q4_K_M.gguf** - Excellent reasoning
+- **Llama-3.1-70B-Instruct-Q4_K_M.gguf** - Top-tier performance (requires significant RAM)
+
+### Downloading Models
+
+#### Method 1: Hugging Face
+
+```bash
+# Example: Download Qwen 1.5B model
+pip install huggingface_hub
+python -c "
+from huggingface_hub import hf_hub_download
+hf_hub_download(
+    repo_id='Qwen/Qwen2.5-1.5B-Instruct-GGUF',
+    filename='qwen2.5-1.5b-instruct-q4_k_m.gguf',
+    local_dir='/models'
+)
+"
+```
+
+#### Method 2: Direct Download
+
+```bash
+# Create models directory
+sudo mkdir -p /models
+sudo chmod 755 /models
+
+# Download model (example URLs - replace with actual URLs)
+wget -O /models/qwen.gguf https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf
+```
+
+#### Method 3: Using Model Managers
+
+```bash
+# Using ollama (if installed)
+ollama pull qwen2.5:1.5b
+# Then locate the GGUF file in ollama's model directory and copy to /models/
+```
+
+### Model Organization
+
+```
+/models/
+├── qwen.gguf              # Default model (named for easy reference)
+├── llama2-7b.gguf         # Larger model for complex tasks
+├── mistral-7b.gguf        # Alternative model
+└── gemma-2b.gguf          # Small fast model
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create or edit your shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+# Default model to use
+export MODEL=qwen
+
+# Debug level (0=off, 1=basic, 2=verbose)
+export DEBUG=0
+
+# Optional: Custom model directory
+export PEDICAB_MODELS_DIR="/models"
+
+# Optional: Python backend path (usually not needed)
+export PEDICAB_PYTHON_PATH="/usr/bin/python3"
+```
+
+Apply the changes:
+
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### System-wide Installation
+
+#### Install Python Backend System-wide
+
+```bash
+# Copy Python backend to system location
+sudo cp lib/pedicab.py /usr/lib/
+sudo cp lib/pedicab.sh /usr/bin/pedicab
+sudo chmod +x /usr/bin/pedicab
+
+# Make models directory system-wide
+sudo mkdir -p /models
+sudo chmod 755 /models
+```
+
+#### Create Wrapper Script (Optional)
+
+Create `/usr/local/bin/pedicab-ruby`:
+
+```bash
+#!/bin/bash
+export MODEL=${MODEL:-qwen}
+export DEBUG=${DEBUG:-0}
+ruby -r pedicab -e "$@"
+```
+
+Make it executable:
+
+```bash
+sudo chmod +x /usr/local/bin/pedicab-ruby
+```
+
+### Development Configuration
+
+For development, you might want to set up:
+
+```bash
+# Development environment
+export PEDICAB_DEV=1
+export PEDICAB_MODELS_DIR="./models"  # Local models directory
+export DEBUG=2  # Verbose debugging
+```
+
+---
+
+## Verification
+
+### Basic Installation Test
+
+Create a test script `test_pedicab.rb`:
+
+```ruby
+#!/usr/bin/env ruby
+require 'pedicab'
+
+puts "Testing Pedicab installation..."
+
+# Test 1: Check models
+puts "Available models: #{Pedicab.models.inspect}"
+
+# Test 2: Basic conversation
+begin
+  ai = Pedicab['test']
+  response = ai["Say 'Hello, World!'"]
+  puts "Response: #{response.out}"
+  puts "Time: #{response.took}s"
+  
+  if response.out.include?("Hello")
+    puts "✓ Basic conversation test passed"
+  else
+    puts "✗ Unexpected response"
+  end
+rescue => e
+  puts "✗ Error: #{e.message}"
+end
+
+# Test 3: Conditional logic
+begin
+  if ai.ride.if?("1+1 equals 2")
+    puts "✓ Conditional logic test passed"
+  else
+    puts "✗ Conditional logic test failed"
+  end
+rescue => e
+  puts "✗ Error in conditional test: #{e.message}"
+end
+
+puts "Testing complete!"
+```
+
+Run the test:
+
+```bash
+ruby test_pedicab.rb
+```
+
+### Performance Benchmark
+
+Create `benchmark.rb`:
+
+```ruby
+require 'pedicab'
+require 'benchmark'
+
+puts "Running Pedicab performance benchmark..."
+
+ai = Pedicab['benchmark']
+prompts = [
+  "What is Ruby?",
+  "Explain variables",
+  "What are loops?",
+  "Define functions",
+  "How does OOP work?"
+]
+
+total_time = Benchmark.realtime do
+  prompts.each_with_index do |prompt, i|
+    puts "Test #{i + 1}: #{prompt}"
+    response = ai[prompt]
+    puts "  Response time: #{response.took.round(3)}s"
+    puts "  Response length: #{response.out.length} chars"
+    puts
+  end
+end
+
+puts "Total time: #{total_time.round(3)}s"
+puts "Average per request: #{(total_time / prompts.length).round(3)}s"
+puts "Total conversation time: #{ai.life.round(3)}s"
+```
+
+Run the benchmark:
+
+```bash
+ruby benchmark.rb
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "No such file or directory - pedicab"
+
+**Problem**: The Python backend script isn't found.
+
+**Solutions**:
+```bash
+# Check if pedicab command exists
+which pedicab
+
+# Install system-wide
+sudo cp lib/pedicab.py /usr/lib/
+sudo cp lib/pedicab.sh /usr/bin/pedicab
+sudo chmod +x /usr/bin/pedicab
+
+# Or update PATH
+export PATH="$PATH:$(pwd)/lib"
+```
+
+#### 2. "Model file not found"
+
+**Problem**: The specified GGUF model doesn't exist.
+
+**Solutions**:
+```bash
+# Check models directory
+ls -la /models/
+
+# Check model naming
+export MODEL="qwen"  # Don't include .gguf extension
+
+# Download a model
+wget -O /models/qwen.gguf [model-url]
+```
+
+#### 3. "llama-cpp-python not found"
+
+**Problem**: Python dependency missing.
+
+**Solutions**:
+```bash
+# Install llama-cpp-python
+pip install llama-cpp-python
+
+# With hardware acceleration (if supported)
+pip install llama-cpp-python --prefer-binary --extra-index-url=https://jllllll.github.io/llama-cpp-python-cuBLAS-wheels/AVX2/cu118
+
+# Verify installation
+python -c "import llama_cpp; print('llama-cpp-python installed')"
+```
+
+#### 4. "Permission denied" errors
+
+**Problem**: File permission issues.
+
+**Solutions**:
+```bash
+# Fix models directory permissions
+sudo chmod 755 /models
+sudo chown $USER:$USER /models/*.gguf
+
+# Fix script permissions
+chmod +x lib/pedicab.sh
+```
+
+#### 5. "Out of memory" errors
+
+**Problem**: Model too large for available RAM.
+
+**Solutions**:
+```bash
+# Use a smaller model
+export MODEL="gemma"  # Instead of large models
+
+# Or quantize more aggressively (download Q2 or Q3 versions)
+
+# Monitor memory usage
+free -h
+```
+
+#### 6. Slow responses
+
+**Problem**: Model inference is slow.
+
+**Solutions**:
+```bash
+# Check system resources
+top
+htop
+
+# Use smaller/faster model
+export MODEL="phi-3-mini"
+
+# Enable GPU acceleration (if available)
+pip install llama-cpp-python --prefer-binary --extra-index-url=https://jllllll.github.io/llama-cpp-python-cuBLAS-wheels/AVX2/cu118
+```
+
+### Debug Mode
+
+Enable verbose debugging to diagnose issues:
+
+```bash
+export DEBUG=2
+ruby your_script.rb
+```
+
+Debug output includes:
+- Action descriptions
+- Processing times
+- Full state information
+- Error stack traces
+- Communication protocol details
+
+### Log Collection
+
+For bug reports, collect this information:
+
+```bash
+# System info
+ruby -v
+python -c "import llama_cpp; print(llama_cpp.__version__)"
+
+# Environment
+env | grep -E "(MODEL|DEBUG|PEDICAB)"
+
+# Models
+ls -la /models/
+
+# Test with debugging
+DEBUG=2 ruby -e "require 'pedicab'; puts Pedicab['test']['Hello']"
+```
+
+---
+
+## Platform-Specific Notes
+
+### Linux
+
+#### Ubuntu/Debian
+```bash
+# Install Ruby
+sudo apt update
+sudo apt install ruby ruby-dev build-essential
+
+# Install Python
+sudo apt install python3 python3-pip
+
+# Install dependencies
+sudo gem install pedicab
+pip3 install llama-cpp-python
+```
+
+#### CentOS/RHEL/Fedora
+```bash
+# Ruby
+sudo dnf install ruby ruby-devel
+
+# Python
+sudo dnf install python3 python3-pip
+
+# Development tools
+sudo dnf groupinstall "Development Tools"
+```
+
+### macOS
+
+#### Using Homebrew
+```bash
+# Install Ruby (if system version is too old)
+brew install ruby
+
+# Install Python
+brew install python3
+
+# Install gems
+gem install pedicab
+
+# Install Python packages
+pip3 install llama-cpp-python
+```
+
+#### Using MacPorts
+```bash
+# Install Ruby
+sudo port install ruby27
+
+# Install Python
+sudo port install python39
+
+# Install packages
+sudo gem install pedicab
+sudo pip3.9 install llama-cpp-python
+```
+
+### Windows (WSL2)
+
+#### Setup WSL2
+```powershell
+# Enable WSL2
+wsl --install
+
+# Install Ubuntu (recommended)
+wsl --install -d Ubuntu
+```
+
+#### Inside WSL2 (Ubuntu)
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install required packages
+sudo apt install ruby ruby-dev build-essential python3 python3-pip -y
+
+# Install gems and Python packages
+gem install pedicab
+pip3 install llama-cpp-python
+```
+
+### Docker Setup
+
+#### Dockerfile
+```dockerfile
+FROM ruby:3.1
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-pip \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+RUN pip3 install llama-cpp-python
+
+# Install Ruby gem
+RUN gem install pedicab
+
+# Create models directory
+RUN mkdir -p /models
+
+# Copy models (ADD your models here)
+# COPY models/ /models/
+
+# Set environment
+ENV MODEL=qwen
+ENV DEBUG=0
+
+# Add script
+COPY your_script.rb /app/
+WORKDIR /app
+
+CMD ["ruby", "your_script.rb"]
+```
+
+#### Docker Compose
+```yaml
+version: '3.8'
+services:
+  pedicab-app:
+    build: .
+    volumes:
+      - ./models:/models:ro
+      - ./logs:/app/logs
+    environment:
+      - MODEL=qwen
+      - DEBUG=0
+    command: ruby app.rb
+```
+
+---
+
+## Advanced Configuration
+
+### Custom Model Directory
+
+```ruby
+# In your Ruby code
+ENV['PEDICAB_MODELS_DIR'] = '/path/to/my/models'
+
+# Or in environment
+export PEDICAB_MODELS_DIR="/path/to/my/models"
+```
+
+### Custom Python Backend
+
+```ruby
+# Override Python backend path
+ENV['PEDICAB_PYTHON_PATH'] = '/usr/local/bin/python3'
+```
+
+### Performance Tuning
+
+#### For CPU-only systems:
+```bash
+# Optimize for CPU
+export OMP_NUM_THREADS=4  # Adjust based on your CPU cores
+```
+
+#### For GPU systems:
+```bash
+# Install CUDA-enabled llama-cpp-python
+pip install llama-cpp-python --prefer-binary --extra-index-url=https://jllllll.github.io/llama-cpp-python-cuBLAS-wheels/AVX2/cu118
+```
+
+---
+
+## Next Steps
+
+After successful installation:
+
+1. **Read the main README** for basic usage
+2. **Check the API documentation** for detailed method reference
+3. **Try the examples** to see practical implementations
+4. **Join the community** for support and discussions
+
+If you encounter any issues during installation, please check the troubleshooting section or create an issue on the GitHub repository.
+
+---
+
+*Having trouble? Check our [GitHub Issues](https://github.com/xorgnak/pedicab/issues) for common solutions.*