Skip to content

INSTALLATION.md

Latest commit

 

History

History
439 lines (316 loc) · 8.06 KB

INSTALLATION.md

File metadata and controls

439 lines (316 loc) · 8.06 KB

Installation Guide 🚀

This guide will walk you through installing and setting up CodeHealer in your Ruby on Rails application.

📋 Prerequisites

Before installing CodeHealer, ensure you have:

  • Ruby 2.7.0 or higher
  • Rails 6.0.0 or higher
  • Git repository initialized
  • GitHub account (for pull request creation)
  • OpenAI API key (for API-based evolution)
  • Claude Code terminal (for local evolution)

🔧 Step-by-Step Installation

1. Add to Gemfile

Add the gem to your Gemfile:

# Gemfile
source 'https://rubygems.org'

# ... other gems ...

# CodeHealer - AI-powered code healing and self-repair system
gem 'code_healer'

# Required dependencies (if not already present)
gem 'sidekiq', '>= 6.0.0'
gem 'redis', '>= 4.0.0'

2. Install Dependencies

Run bundle install:

bundle install

3. Copy Configuration

Copy the example configuration file:

cp config/code_healer.yml.example config/code_healer.yml

4. Configure CodeHealer

Edit config/code_healer.yml with your settings:

---
enabled: true

# Classes that are allowed to evolve
allowed_classes:
  - User
  - Order
  - PaymentProcessor

# Evolution strategy
evolution_strategy:
  method: "api"  # or "claude_code_terminal" or "hybrid"

# API configuration
api:
  provider: "openai"
  model: "gpt-4"
  api_key: <%= ENV['OPENAI_API_KEY'] %>

# Business context
business_context:
  enabled: true
  User:
    domain: "User Management"
    key_rules:
      - "Email must be unique and valid"

5. Set Environment Variables

Create or update your .env file:

# .env
OPENAI_API_KEY=your_openai_api_key_here
GITHUB_TOKEN=your_github_token_here

Important: Never commit API keys to version control!

6. Setup Sidekiq (Recommended)

Create config/sidekiq.yml:

:concurrency: 5
:queues:
  - [evolution, 2]
  - [default, 1]

Add to config/routes.rb:

# config/routes.rb
require 'sidekiq/web'

Rails.application.routes.draw do
  # ... other routes ...
  
  # Sidekiq Web UI (optional, for monitoring)
  mount Sidekiq::Web => '/sidekiq'
end

7. Setup Redis

Ensure Redis is running:

# macOS with Homebrew
brew services start redis

# Ubuntu/Debian
sudo systemctl start redis

# Or run manually
redis-server

8. Business Requirements (Optional)

Create a business_requirements/ directory in your project root:

mkdir business_requirements

Add markdown files with your business rules:

# business_requirements/user_management.md
# User Management Business Rules

## Authentication
- Users must have valid email addresses
- Passwords must be at least 8 characters
- Failed login attempts should be logged

## Data Validation
- All user input must be sanitized
- Email uniqueness is enforced at database level

🚀 Quick Start Example

1. Create a Test Model

# app/models/user.rb
class User < ApplicationRecord
  def calculate_discount(amount, percentage)
    # This will trigger evolution if an error occurs
    amount * (percentage / 100.0)
  end
end

2. Test Evolution

Start your Rails server and trigger an error:

rails server

In another terminal, trigger an error:

curl -X POST http://localhost:3000/api/users/calculate_discount \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "percentage": nil}'

3. Watch Evolution in Action

Check the logs to see CodeHealer in action:

tail -f log/development.log

🔍 Verification

Check Installation

Verify CodeHealer is properly installed:

# In Rails console
rails console

# Check if CodeHealer is loaded
CodeHealer::VERSION
# Should return the version number

# Check configuration
CodeHealer::ConfigManager.config
# Should return your configuration hash

Check Sidekiq

Verify Sidekiq is working:

# Start Sidekiq
bundle exec sidekiq

# Check Sidekiq Web UI
open http://localhost:3000/sidekiq

Check Business Context

Verify business context is loading:

# In Rails console
CodeHealer::BusinessContextManager.get_context_for_error(
  ArgumentError.new("test"), 
  "User", 
  "calculate_discount"
)

🛠️ Configuration Options

Core Settings

Setting Description Default Required
enabled Enable/disable CodeHealer true Yes
allowed_classes Classes that can evolve [] Yes
excluded_classes Classes that should never evolve [] No
allowed_error_types Error types that trigger evolution [] No

Evolution Strategy

Strategy Description Use Case
api Use OpenAI API for fixes Production, cloud-based
claude_code_terminal Use local Claude Code agent Development, offline
hybrid Try Claude Code first, fallback to API Best of both worlds

Business Context

business_context:
  enabled: true
  
  User:
    domain: "User Management"
    key_rules:
      - "Email must be unique and valid"
    validation_patterns:
      - "Input validation for all parameters"

Git Operations

git:
  auto_commit: true
  auto_push: true
  branch_prefix: evolve
  pr_target_branch: main

pull_request:
  enabled: true
  auto_create: true
  labels: ["auto-fix", "self-evolving"]

🔒 Security Configuration

API Keys

Store sensitive data in environment variables:

# config/self_evolution.yml
api:
  provider: "openai"
  api_key: <%= ENV['OPENAI_API_KEY'] %>
  model: "gpt-4"

Class Restrictions

Carefully configure which classes can evolve:

allowed_classes:
  - User
  - Order
  - PaymentProcessor

excluded_classes:
  - ApplicationController
  - ApplicationRecord
  - ApplicationJob
  - ApplicationMailer

Business Rule Validation

Enable business rule validation:

business_context:
  enabled: true
  validate_rules: true
  strict_mode: true

🧪 Testing Configuration

Test Environment

Disable evolution in test environment:

# config/environments/test.rb
Rails.application.configure do
  # ... other config ...
  
  # Disable CodeHealer in tests
  config.self_evolving = {
    enabled: false,
    mock_ai_responses: true,
    dry_run: true
  }
end

Mock Responses

Use mock responses for testing:

# config/self_evolution.yml
test:
  enabled: false
  mock_ai_responses: true
  mock_response: "def calculate_discount(amount, percentage)\n  return 0 if amount.nil? || percentage.nil?\n  amount * (percentage / 100.0)\nend"

🚨 Troubleshooting

Common Installation Issues

  1. Gem not found

    bundle install
bundle exec rails console

  2. Configuration not loading

    • Check file path: config/self_evolution.yml
    • Verify YAML syntax
    • Check file permissions

  3. Sidekiq not working

    # Check Redis
redis-cli ping

# Check Sidekiq
bundle exec sidekiq -V

  4. Business context not loading

    • Verify business_requirements/ directory exists
    • Check markdown file syntax
    • Verify file permissions

Debug Mode

Enable debug logging:

# config/self_evolution.yml
logging:
  level: debug
  show_thinking_process: true
  verbose: true

Log Files

Check relevant log files:

# Rails logs
tail -f log/development.log

# Sidekiq logs
tail -f log/sidekiq.log

# Redis logs
tail -f /var/log/redis/redis-server.log

📚 Next Steps

After successful installation:

  1. Read the README for comprehensive usage information
  2. Check Configuration for advanced options
  3. Review Examples for practical use cases
  4. Join Discussions for community support

🆘 Need Help?

Happy Evolving! 🚀