rails_ai 0.1.0

data/STRUCTURE.md

@@ -0,0 +1,139 @@
+# Rails AI - Complete Structure
+
+This Rails AI gem is designed to be a comprehensive AI toolkit that's deeply integrated into Rails applications, supporting Rails 5.2+ through Rails 8 with Ruby 3.x compatibility.
+
+## Directory Structure
+
+```
+rails_ai/
+├─ README.md                    # Comprehensive documentation
+├─ rails_ai.gemspec            # Gem specification with Rails 5.2-8.0 support
+├─ Gemfile                     # Development dependencies
+├─ Rakefile                    # Rake tasks for testing and linting
+├─ LICENSE                     # MIT License
+├─ .gitignore                  # Git ignore patterns
+├─ Appraisals                  # Multi-Rails version testing
+├─ lib/
+│ ├─ rails_ai.rb              # Main module with version compatibility
+│ ├─ rails_ai/
+│ │ ├─ version.rb             # Version constant
+│ │ ├─ config.rb              # Configuration with Struct
+│ │ ├─ context.rb             # CurrentAttributes for context
+│ │ ├─ cache.rb               # Intelligent caching
+│ │ ├─ redactor.rb            # Content redaction for security
+│ │ ├─ events.rb              # Event logging and metrics
+│ │ ├─ provider.rb            # Provider base classes
+│ │ ├─ engine.rb              # Rails engine with version compatibility
+│ │ ├─ railtie.rb             # Railtie with version-specific configs
+│ │ └─ providers/
+│ │   ├─ base.rb              # Base provider interface
+│ │   ├─ openai_adapter.rb    # OpenAI integration
+│ │   └─ dummy_adapter.rb     # Dummy provider for testing
+│ └─ generators/
+│   └─ rails_ai/
+│     ├─ install/
+│     │ ├─ install_generator.rb
+│     │ └─ templates/         # Generator templates
+│     └─ feature/
+│       ├─ feature_generator.rb
+│       └─ templates/         # Feature templates
+├─ app/
+│ ├─ channels/
+│ │ └─ ai_stream_channel.rb   # Action Cable streaming
+│ ├─ components/
+│ │ └─ ai/
+│ │   └─ prompt_component.rb  # ViewComponent for AI UI
+│ ├─ controllers/
+│ │ └─ concerns/ai/
+│ │   └─ streaming.rb         # Streaming controller concern
+│ ├─ helpers/
+│ │ └─ ai_helper.rb           # AI helper methods
+│ ├─ jobs/
+│ │ └─ ai/
+│ │   ├─ generate_embedding_job.rb
+│ │   └─ generate_summary_job.rb
+│ ├─ models/
+│ │ └─ concerns/ai/
+│ │   └─ embeddable.rb        # Model concern for embeddings
+│ └─ views/
+│   └─ rails_ai/
+│     └─ dashboard/
+│       └─ index.html.erb     # Dashboard view
+├─ config/
+│ └─ routes.rb                # Engine routes
+└─ spec/
+  ├─ spec_helper.rb           # RSpec configuration
+  └─ rails_ai_spec.rb         # Main test suite
+```
+
+## Key Features
+
+### Rails Version Compatibility
+- **Rails 5.2+**: Full backward compatibility
+- **Rails 6.0, 6.1**: Enhanced features
+- **Rails 7.0, 7.1**: Importmap support, enhanced streaming
+- **Rails 8.0**: Latest features, enhanced performance
+
+### Ruby Version Support
+- **Ruby 3.0+**: Primary target
+- **Ruby 2.7+**: Backward compatibility
+
+### Core AI Capabilities
+- **Universal Interface**: `RailsAi.chat()`, `RailsAi.stream()`, `RailsAi.embed()`
+- **Multiple Providers**: OpenAI, custom adapters, dummy for testing
+- **Intelligent Caching**: Cost optimization with configurable TTL
+- **Content Security**: Built-in redaction for PII
+- **Observability**: Comprehensive event logging
+- **Streaming**: Real-time AI responses via Action Cable
+
+### Rails Integration
+- **Generators**: Easy setup and feature generation
+- **View Components**: Reusable AI UI components
+- **Jobs**: Background AI processing
+- **Models**: Embeddable concern for semantic search
+- **Helpers**: Convenient AI methods
+- **Controllers**: Streaming concerns
+
+### Testing & Quality
+- **Multi-Rails Testing**: Appraisal for version compatibility
+- **RSpec**: Comprehensive test suite
+- **Standard**: Code style enforcement
+- **CI/CD**: GitHub Actions for multiple Rails/Ruby versions
+
+## Usage Examples
+
+```ruby
+# Basic AI operations
+RailsAi.chat("Write a blog post about Ruby")
+RailsAi.stream("Explain quantum computing") { |token| puts token }
+RailsAi.embed(["Ruby on Rails", "Django"])
+
+# Convenience methods
+RailsAi.summarize(long_article)
+RailsAi.translate("Hello", "Spanish")
+RailsAi.classify("Great product!", ["positive", "negative"])
+RailsAi.generate_code("User authentication", language: "ruby")
+
+# Rails integration
+class Article < ApplicationRecord
+  include RailsAi::Embeddable
+end
+
+# View components
+<%= render RailsAi::PromptComponent.new(prompt: "Ask me anything") %>
+```
+
+## Configuration
+
+```ruby
+# config/initializers/rails_ai.rb
+RailsAi.configure do |config|
+  config.provider = :openai
+  config.default_model = "gpt-4o-mini"
+  config.token_limit = 4000
+  config.cache_ttl = 1.hour
+  config.stub_responses = Rails.env.test?
+end
+```
+
+This structure provides a solid foundation for building AI-powered Rails applications with full backward compatibility and forward-looking features.

data/USAGE_GUIDE.md

@@ -0,0 +1,288 @@
+# Rails AI - Quick Usage Guide
+
+## 🚀 Getting Started
+
+### 1. Installation
+```bash
+# Add to Gemfile
+gem 'rails_ai'
+
+# Install
+bundle install
+
+# Generate initial files
+rails generate rails_ai:install
+```
+
+### 2. Configuration
+```ruby
+# config/initializers/rails_ai.rb
+RailsAi.configure do |config|
+  config.provider = :openai
+  config.default_model = "gpt-4o-mini"
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.cache_ttl = 1.hour
+  config.stub_responses = Rails.env.test?
+end
+```
+
+## 📝 Basic Usage
+
+### Text Operations
+```ruby
+# Simple chat
+RailsAi.chat("Write a blog post about Ruby")
+
+# Streaming
+RailsAi.stream("Explain quantum computing") do |token|
+  puts token
+end
+
+# Common tasks
+RailsAi.summarize(long_text)
+RailsAi.translate("Hello", "Spanish")
+RailsAi.classify("Great product!", ["positive", "negative"])
+```
+
+### Image Operations
+```ruby
+# Generate image
+image = RailsAi.generate_image("A sunset over mountains")
+
+# Analyze image
+analysis = RailsAi.analyze_image(image_file, "What do you see?")
+
+# Edit image
+edited = RailsAi.edit_image(image_file, "Add a rainbow")
+```
+
+### Video Operations
+```ruby
+# Generate video
+video = RailsAi.generate_video("A cat playing", duration: 10)
+
+# Analyze video
+analysis = RailsAi.analyze_video(video_file, "What's happening?")
+```
+
+### Audio Operations
+```ruby
+# Generate speech
+speech = RailsAi.generate_speech("Hello world", voice: "alloy")
+
+# Transcribe audio
+text = RailsAi.transcribe_audio(audio_file)
+```
+
+## 🧠 Context-Aware Usage
+
+### In Controllers
+```ruby
+class PostsController < ApplicationController
+  include RailsAi::ContextAware
+
+  def analyze_image
+    # Automatically includes user and window context
+    result = analyze_image_with_context(
+      params[:image], 
+      "What's in this image?"
+    )
+    render json: { analysis: result }
+  end
+end
+```
+
+### Manual Context
+```ruby
+# With custom context
+RailsAi.analyze_image_with_context(
+  image_file,
+  "What do you see?",
+  user_context: { id: 1, role: "admin" },
+  window_context: { controller: "PostsController" },
+  image_context: { format: "png" }
+)
+```
+
+## 🎨 Rails Integration
+
+### View Components
+```erb
+<!-- AI Chat -->
+<%= render RailsAi::PromptComponent.new(
+  prompt: "Ask me anything",
+  stream_id: ai_stream_id
+) %>
+
+<!-- Image Generation Form -->
+<%= form_with url: ai_generate_image_path do |form| %>
+  <%= form.text_area :prompt, placeholder: "Describe the image" %>
+  <%= form.submit "Generate Image" %>
+<% end %>
+```
+
+### Helpers
+```erb
+<!-- In views -->
+<%= ai_chat("Write a summary") %>
+<%= ai_generate_image("A beautiful landscape") %>
+<%= ai_analyze_image_with_context(image, "What do you see?") %>
+```
+
+### Jobs
+```ruby
+class GenerateContentJob < ApplicationJob
+  def perform(prompt)
+    RailsAi.chat(prompt)
+  end
+end
+
+# Queue the job
+GenerateContentJob.perform_later("Write a blog post")
+```
+
+### Models
+```ruby
+class Article < ApplicationRecord
+  include RailsAi::Embeddable
+  
+  def generate_summary!
+    RailsAi.summarize(content)
+  end
+  
+  def generate_thumbnail!
+    RailsAi.generate_image("Thumbnail for: #{title}")
+  end
+end
+```
+
+## 🔧 Advanced Usage
+
+### Custom Providers
+```ruby
+class MyProvider < RailsAi::Providers::Base
+  def chat!(messages:, model:, **opts)
+    # Your custom implementation
+  end
+end
+
+# Use in configuration
+RailsAi.configure do |config|
+  config.provider = :my_provider
+end
+```
+
+### Streaming with Action Cable
+```ruby
+class ChatController < ApplicationController
+  def stream
+    RailsAi.stream(params[:prompt]) do |token|
+      ActionCable.server.broadcast("chat_#{params[:room_id]}", {
+        type: "token",
+        content: token
+      })
+    end
+  end
+end
+```
+
+### Caching
+```ruby
+# Automatic caching
+RailsAi.chat("Expensive operation") # Cached automatically
+
+# Custom cache
+RailsAi::Cache.fetch([:custom, user.id, prompt.hash]) do
+  RailsAi.chat(prompt)
+end
+```
+
+## 🧪 Testing
+
+```ruby
+# In your tests
+RSpec.describe "AI Features" do
+  before do
+    RailsAi.configure do |config|
+      config.provider = :dummy
+      config.stub_responses = true
+    end
+  end
+
+  it "generates content" do
+    result = RailsAi.chat("Hello")
+    expect(result).to be_a(String)
+  end
+end
+```
+
+## 🎯 Common Patterns
+
+### Content Generation
+```ruby
+# Blog post
+post = RailsAi.chat("Write a blog post about #{topic}")
+
+# Product description
+description = RailsAi.chat("Write a product description for #{product_name}")
+
+# Email content
+email = RailsAi.chat("Write a marketing email about #{campaign}")
+```
+
+### Image Processing
+```ruby
+# Generate product images
+image = RailsAi.generate_image("Product photo of #{product_name}")
+
+# Analyze user uploads
+analysis = RailsAi.analyze_image(uploaded_file, "Is this appropriate for our site?")
+
+# Create variations
+variations = RailsAi.create_variation(existing_image)
+```
+
+### Data Analysis
+```ruby
+# Sentiment analysis
+sentiment = RailsAi.classify(user_feedback, ["positive", "negative", "neutral"])
+
+# Extract information
+entities = RailsAi.extract_entities("Apple Inc. was founded by Steve Jobs")
+
+# Summarize content
+summary = RailsAi.summarize(long_document)
+```
+
+## 🚨 Best Practices
+
+1. **Always use context** when available for better results
+2. **Cache expensive operations** to reduce costs
+3. **Use background jobs** for heavy AI operations
+4. **Test with dummy providers** in development
+5. **Monitor API usage** and costs
+6. **Handle errors gracefully** in production
+7. **Use streaming** for better user experience
+8. **Sanitize inputs** before sending to AI
+
+## 🔍 Troubleshooting
+
+### Common Issues
+- **API Key Missing**: Set `OPENAI_API_KEY` environment variable
+- **Rate Limits**: Implement retry logic and rate limiting
+- **Memory Issues**: Use background jobs for large operations
+- **Context Not Working**: Ensure controller includes `RailsAi::ContextAware`
+
+### Debug Mode
+```ruby
+# Enable debug logging
+Rails.logger.level = :debug
+
+# Check configuration
+RailsAi.config.provider
+RailsAi.config.default_model
+```
+
+---
+
+**Need Help?** Check the [full documentation](README.md) or [open an issue](https://github.com/yourusername/rails_ai/issues)!

data/app/channels/ai_stream_channel.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsAi
+  class AiStreamChannel < ApplicationCable::Channel
+    def subscribed
+      stream_from "ai_stream_#{params[:stream_id]}"
+    end
+
+    def unsubscribed
+      # Any cleanup needed when channel is unsubscribed
+    end
+
+    def stream_ai(data)
+      stream_id = data["stream_id"]
+      prompt = data["prompt"]
+      model = data["model"] || RailsAi.config.default_model
+
+      RailsAi.provider.stream_chat!(
+        messages: [{role: "user", content: prompt}],
+        model: model
+      ) do |token|
+        ActionCable.server.broadcast("ai_stream_#{stream_id}", {
+          type: "token",
+          content: token
+        })
+      end
+
+      ActionCable.server.broadcast("ai_stream_#{stream_id}", {
+        type: "complete"
+      })
+    end
+  end
+end

data/app/components/ai/prompt_component.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAi
+  class PromptComponent < ViewComponent::Base
+    def initialize(prompt:, model: nil, stream_id: nil, placeholder: "Ask me anything...", **options)
+      @prompt = prompt
+      @model = model || RailsAi.config.default_model
+      @stream_id = stream_id || SecureRandom.uuid
+      @placeholder = placeholder
+      @options = options
+    end
+
+    private
+
+    attr_reader :prompt, :model, :stream_id, :placeholder, :options
+
+    def ai_endpoint
+      Rails.application.routes.url_helpers.rails_ai_api_v1_chat_index_path
+    end
+
+    def stream_endpoint
+      Rails.application.routes.url_helpers.rails_ai_streams_path
+    end
+  end
+end

data/app/controllers/concerns/ai/context_aware.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RailsAi
+  module ContextAware
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_ai_context, if: :ai_context_enabled?
+    end
+
+    def ai_context_analyzer
+      @ai_context_analyzer ||= RailsAi::ContextAnalyzer.new(
+        user_context: ai_user_context,
+        window_context: ai_window_context,
+        image_context: ai_image_context
+      )
+    end
+
+    def analyze_image_with_context(image, prompt, **opts)
+      ai_context_analyzer.analyze_with_context(image, prompt, **opts)
+    end
+
+    def generate_with_context(prompt, **opts)
+      ai_context_analyzer.generate_with_context(prompt, **opts)
+    end
+
+    def generate_image_with_context(prompt, **opts)
+      ai_context_analyzer.generate_image_with_context(prompt, **opts)
+    end
+
+    private
+
+    def set_ai_context
+      RailsAi::Context.current_user_id = current_user&.id
+      RailsAi::Context.current_request_id = request.uuid
+    end
+
+    def ai_context_enabled?
+      respond_to?(:current_user) || respond_to?(:current_admin)
+    end
+
+    def ai_user_context
+      return {} unless respond_to?(:current_user) && current_user
+
+      {
+        id: current_user.id,
+        email: current_user.respond_to?(:email) ? current_user.email : nil,
+        role: current_user.respond_to?(:role) ? current_user.role : 'user',
+        created_at: current_user.created_at,
+        last_sign_in_at: current_user.respond_to?(:last_sign_in_at) ? current_user.last_sign_in_at : nil,
+        preferences: extract_user_preferences
+      }.compact
+    end
+
+    def ai_window_context
+      RailsAi::WindowContext.from_controller(self).to_h
+    end
+
+    def ai_image_context
+      # This can be overridden in controllers to provide image-specific context
+      {}
+    end
+
+    def extract_user_preferences
+      return {} unless current_user.respond_to?(:preferences)
+
+      case current_user.preferences
+      when Hash
+        current_user.preferences
+      when String
+        JSON.parse(current_user.preferences) rescue {}
+      else
+        {}
+      end
+    end
+  end
+end

data/app/controllers/concerns/ai/streaming.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsAi
+  module Streaming
+    extend ActiveSupport::Concern
+
+    def stream_ai_response(prompt, model: nil, &block)
+      model ||= RailsAi.config.default_model
+
+      RailsAi.provider.stream_chat!(
+        messages: [{role: "user", content: prompt}],
+        model: model
+      ) do |token|
+        block.call(token) if block_given?
+      end
+    end
+
+    def broadcast_ai_stream(stream_id, prompt, model: nil)
+      model ||= RailsAi.config.default_model
+
+      ActionCable.server.broadcast("ai_stream_#{stream_id}", {
+        type: "start",
+        stream_id: stream_id
+      })
+
+      RailsAi.provider.stream_chat!(
+        messages: [{role: "user", content: prompt}],
+        model: model
+      ) do |token|
+        ActionCable.server.broadcast("ai_stream_#{stream_id}", {
+          type: "token",
+          content: token
+        })
+      end
+
+      ActionCable.server.broadcast("ai_stream_#{stream_id}", {
+        type: "complete"
+      })
+    end
+  end
+end