ragify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a8b50afa93cb29e25eda8a6e6c1bc902ed50b106bbb1b18db1c607672c92d86
+  data.tar.gz: 02f99522340f1a8c2738c6fbc12c45e50fbfb5de4db9771580881a13385b6c11
+SHA512:
+  metadata.gz: 15c94ec278c69c2615c32ae88bd84bece4fec6d1cde2d524cebcd5ddc512152a15c4e2c4b138036baf3ab978940ae3412e4323342e6e10f89afa101896b4f58b
+  data.tar.gz: 280a443ad84ed106454fbad4ac76b6ea0604ce6c80f2e74af02d350eda1c5a9c875db547dd28ab5cdc5372136a62432cc6bc9d41ccd1b03940abae308a1e4a34

data/README.md

@@ -0,0 +1,178 @@
+# Ragify
+
+RAG (Retrieval-Augmented Generation) for Rails. Add semantic search and AI chat to any ActiveRecord model using pgvector and OpenAI.
+
+No external vector databases. No complex infrastructure. Just your PostgreSQL and a few lines of code.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.0
+- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) extension
+- OpenAI API key
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ragify"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configure
+
+```ruby
+# config/initializers/ragify.rb
+Ragify.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.embedding_model = "text-embedding-3-small"  # default
+  config.chat_model = "gpt-4o-mini"                  # default
+  config.similarity_threshold = 0.2                   # default
+end
+```
+
+### 2. Add embedding column
+
+```bash
+rails generate ragify:install FaqEntry
+rails db:migrate
+```
+
+This creates a migration that adds a `vector` column with an IVFFlat index.
+
+### 3. Include in your model
+
+```ruby
+class FaqEntry < ApplicationRecord
+  include Ragify::Embeddable
+
+  ragify_content { |record| "#{record.question} #{record.answer}" }
+end
+```
+
+### 4. Use it
+
+```ruby
+# Semantic search
+results = FaqEntry.semantic_search("how does cashback work?")
+# => [{ record: #<FaqEntry>, content: "...", similarity: 0.87 }, ...]
+
+# RAG chat (search + LLM)
+response = Ragify.chat("how does cashback work?",
+  context_model: FaqEntry,
+  system_prompt: "You are a helpful assistant for a loyalty program."
+)
+# => { answer: "Cashback is automatically...", context: [...], tokens: 342 }
+
+# Generate embeddings for existing records
+FaqEntry.embed_all!
+```
+
+## Features
+
+### Embeddable
+
+Include `Ragify::Embeddable` in any ActiveRecord model. Embeddings are automatically generated on create/update.
+
+```ruby
+class Article < ApplicationRecord
+  include Ragify::Embeddable
+
+  # Block form - full control over content
+  ragify_content { |r| "#{r.title}\n#{r.body}" }
+
+  # Or method form
+  ragify_content :embedding_text
+end
+```
+
+### Semantic Search
+
+Find records by meaning, not keywords.
+
+```ruby
+Article.semantic_search("climate change effects",
+  limit: 10,           # max results (default: 5)
+  threshold: 0.3       # min similarity 0-1 (default: 0.2)
+)
+```
+
+Returns an array of hashes with `:record`, `:content`, and `:similarity`.
+
+### RAG Chat
+
+Combine semantic search with an LLM for context-aware answers.
+
+```ruby
+Ragify.chat("what's your refund policy?",
+  context_model: FaqEntry,
+  system_prompt: "You are a customer support agent.",
+  search_limit: 5,
+  history: [
+    { role: "user", content: "hi" },
+    { role: "assistant", content: "Hello! How can I help?" }
+  ]
+)
+```
+
+Returns a hash:
+
+```ruby
+{
+  answer: "Our refund policy allows...",
+  context: [{ record: ..., content: "...", similarity: 0.91 }],
+  tokens: 487,
+  had_context: true
+}
+```
+
+### Batch Embedding
+
+Generate embeddings for all records (useful for initial setup):
+
+```ruby
+FaqEntry.embed_all!
+
+# Or embed specific records
+Ragify.embed("some text")
+Ragify.embed_batch(["text 1", "text 2", "text 3"])
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `openai_api_key` | `ENV["OPENAI_API_KEY"]` | OpenAI API key |
+| `embedding_model` | `text-embedding-3-small` | Embedding model |
+| `embedding_dimensions` | `1536` | Vector dimensions |
+| `chat_model` | `gpt-4o-mini` | Chat completion model |
+| `max_tokens` | `1000` | Max response tokens |
+| `temperature` | `0.3` | LLM temperature |
+| `similarity_threshold` | `0.2` | Min cosine similarity |
+| `search_limit` | `5` | Default search results |
+| `ivfflat_probes` | `10` | IVFFlat index probes |
+| `logger` | `Rails.logger` | Logger instance |
+
+## How It Works
+
+1. **Embedding**: When a record is saved, `ragify_content` extracts text and sends it to OpenAI's embedding API. The resulting vector is stored in a pgvector column.
+
+2. **Search**: Queries are embedded the same way, then pgvector finds the nearest neighbors using cosine similarity with an IVFFlat index.
+
+3. **Chat**: The search results are injected as context into an LLM prompt, which generates a grounded answer.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/pashgo/ragify.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/generators/ragify/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Ragify
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    argument :model_name, type: :string, desc: "Model to add embeddings to (e.g., FaqEntry)"
+
+    def create_migration
+      migration_template "add_embedding_migration.rb.erb",
+                         "db/migrate/add_ragify_embedding_to_#{table_name}.rb"
+    end
+
+    def show_post_install
+      say ""
+      say "Ragify installed! Next steps:", :green
+      say ""
+      say "  1. Run the migration:"
+      say "     rails db:migrate"
+      say ""
+      say "  2. Add to your model:"
+      say "     class #{model_name} < ApplicationRecord"
+      say "       include Ragify::Embeddable"
+      say '       ragify_content { |r| "#{r.question} #{r.answer}" }'
+      say "     end"
+      say ""
+      say "  3. Generate embeddings for existing records:"
+      say "     #{model_name}.embed_all!"
+      say ""
+      say "  4. Search:"
+      say '     #{model_name}.semantic_search("your query")'
+      say ""
+    end
+
+    private
+
+    def table_name
+      model_name.underscore.pluralize
+    end
+
+    def dimensions
+      Ragify.configuration.embedding_dimensions
+    end
+  end
+end

data/lib/generators/ragify/templates/add_embedding_migration.rb.erb

@@ -0,0 +1,8 @@
+class AddRagifyEmbeddingTo<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    enable_extension "vector" unless extension_enabled?("vector")
+
+    add_column :<%= table_name %>, :embedding, :vector, limit: <%= dimensions %>
+    add_index :<%= table_name %>, :embedding, using: :ivfflat, opclass: :vector_cosine_ops
+  end
+end

data/lib/ragify/chat.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ragify
+  # RAG chat: find relevant context via semantic search, then ask an LLM.
+  #
+  #   Ragify.chat("how does cashback work?",
+  #     context_model: FaqEntry,
+  #     system_prompt: "You are a helpful assistant."
+  #   )
+  #   # => { answer: "Cashback is...", context: [...], tokens: 342 }
+  #
+  class Chat
+    OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions"
+
+    DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant. Answer questions based on the provided context. " \
+      "If the context doesn't contain relevant information, say you don't know."
+
+    def initialize(context_model:, system_prompt: nil, search_limit: nil, history: nil)
+      @context_model = context_model
+      @system_prompt = system_prompt || DEFAULT_SYSTEM_PROMPT
+      @search_limit = search_limit
+      @history = history || []
+    end
+
+    def call(query)
+      search_results = Search.new(@context_model).call(query, limit: @search_limit)
+      context = build_context(search_results)
+      messages = build_messages(query, context)
+
+      response = chat_completion(messages)
+      answer = response.dig("choices", 0, "message", "content")&.strip
+      tokens = response.dig("usage", "total_tokens") || 0
+
+      {
+        answer: answer,
+        context: search_results,
+        tokens: tokens,
+        had_context: search_results.any?
+      }
+    rescue HttpClient::ApiError, Net::OpenTimeout, Net::ReadTimeout => e
+      config.logger.error("[Ragify::Chat] API error: #{e.message}")
+      { answer: nil, context: [], tokens: 0, had_context: false, error: e.message }
+    end
+
+    private
+
+    def build_context(results)
+      return "" if results.empty?
+
+      results.map do |result|
+        "[Relevance: #{(result[:similarity] * 100).round}%]\n#{result[:content]}"
+      end.join("\n\n---\n\n")
+    end
+
+    def build_messages(query, context)
+      messages = [{ role: "system", content: @system_prompt }]
+
+      @history.each do |msg|
+        messages << { role: msg[:role].to_s, content: msg[:content].to_s }
+      end
+
+      user_content = if context.present?
+                       "Context:\n#{context}\n\n---\n\nQuestion: #{query}"
+                     else
+                       query
+                     end
+
+      messages << { role: "user", content: user_content }
+      messages
+    end
+
+    def chat_completion(messages)
+      HttpClient.new.post_json(OPENAI_CHAT_URL, body: {
+        model: config.chat_model,
+        messages: messages,
+        max_tokens: config.max_tokens,
+        temperature: config.temperature
+      }, timeout: 60)
+    end
+
+    def config
+      Ragify.configuration
+    end
+  end
+end

data/lib/ragify/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ragify
+  class Configuration
+    attr_accessor :openai_api_key,
+                  :embedding_model,
+                  :embedding_dimensions,
+                  :chat_model,
+                  :max_tokens,
+                  :temperature,
+                  :similarity_threshold,
+                  :search_limit,
+                  :ivfflat_probes,
+                  :logger
+
+    def initialize
+      @openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+      @embedding_model = "text-embedding-3-small"
+      @embedding_dimensions = 1536
+      @chat_model = "gpt-4o-mini"
+      @max_tokens = 1000
+      @temperature = 0.3
+      @similarity_threshold = 0.2
+      @search_limit = 5
+      @ivfflat_probes = 10
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+
+    def openai_api_key!
+      openai_api_key || raise(Error, "Ragify: openai_api_key is not configured. " \
+        "Set it via Ragify.configure { |c| c.openai_api_key = '...' } or ENV['OPENAI_API_KEY']")
+    end
+  end
+end

data/lib/ragify/embeddable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Ragify
+  # Include in ActiveRecord models to add vector embeddings and semantic search.
+  #
+  #   class FaqEntry < ApplicationRecord
+  #     include Ragify::Embeddable
+  #     ragify_content { |record| "#{record.question} #{record.answer}" }
+  #   end
+  #
+  #   FaqEntry.semantic_search("how does cashback work?")
+  #   FaqEntry.embed_all!
+  #
+  module Embeddable
+    extend ActiveSupport::Concern
+
+    included do
+      has_neighbors :embedding
+
+      scope :with_embedding, -> { where.not(embedding: nil) }
+
+      after_commit :ragify_generate_embedding, on: %i[create update], if: :ragify_content_changed?
+    end
+
+    class_methods do
+      # Define how to build the text content for embedding.
+      #
+      #   ragify_content { |record| "#{record.title} #{record.body}" }
+      #   ragify_content :embedding_text  # calls record.embedding_text
+      #
+      def ragify_content(method_name = nil, &block)
+        if block
+          @ragify_content_proc = block
+        elsif method_name
+          @ragify_content_proc = ->(record) { record.public_send(method_name) }
+        else
+          raise ArgumentError, "ragify_content requires a method name or block"
+        end
+      end
+
+      def ragify_content_proc
+        @ragify_content_proc || raise(Error, "#{name}: call `ragify_content` to define what text to embed")
+      end
+
+      # Search for records semantically similar to the query string.
+      #
+      #   FaqEntry.semantic_search("refund policy", limit: 5, threshold: 0.3)
+      #
+      def semantic_search(query, limit: nil, threshold: nil)
+        Search.new(self).call(query, limit: limit, threshold: threshold)
+      end
+
+      # Generate embeddings for all records (or a subset).
+      #
+      #   FaqEntry.embed_all!
+      #   FaqEntry.where(embedding: nil).embed_all!
+      #
+      def embed_all!(batch_size: 50)
+        client = EmbeddingClient.new
+        find_each(batch_size: batch_size) do |record|
+          text = ragify_content_proc.call(record)
+          embedding = client.generate(text)
+          record.update_column(:embedding, embedding) if embedding # rubocop:disable Rails/SkipsModelValidations
+        end
+      end
+    end
+
+    # Returns the text that will be embedded for this record.
+    def ragify_text
+      self.class.ragify_content_proc.call(self)
+    end
+
+    private
+
+    def ragify_generate_embedding
+      text = ragify_text
+      return if text.blank?
+
+      embedding = Ragify.embed(text)
+      update_column(:embedding, embedding) if embedding # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    def ragify_content_changed?
+      # Always regenerate — the content proc may depend on any attribute
+      true
+    end
+  end
+end

data/lib/ragify/embedding_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ragify
+  class EmbeddingClient
+    OPENAI_URL = "https://api.openai.com/v1/embeddings"
+    MAX_TEXT_LENGTH = 30_000
+
+    def generate(text)
+      return nil if text.nil? || text.to_s.strip.empty?
+
+      response = request(truncate(text))
+      response.dig("data", 0, "embedding")
+    rescue HttpClient::ApiError, Net::OpenTimeout, Net::ReadTimeout => e
+      config.logger.error("[Ragify] Embedding failed: #{e.message}")
+      nil
+    end
+
+    def generate_batch(texts)
+      return [] if texts.nil? || texts.empty?
+
+      truncated = texts.map { |t| truncate(t) }
+      response = request(truncated)
+
+      data = response["data"] || []
+      embeddings = Array.new(texts.size)
+
+      data.each do |item|
+        index = item["index"]
+        embeddings[index] = item["embedding"] if index && index < texts.size
+      end
+
+      embeddings
+    rescue HttpClient::ApiError, Net::OpenTimeout, Net::ReadTimeout => e
+      config.logger.error("[Ragify] Batch embedding failed: #{e.message}")
+      Array.new(texts.size)
+    end
+
+    private
+
+    def request(input)
+      HttpClient.new.post_json(OPENAI_URL, body: { model: config.embedding_model, input: input })
+    end
+
+    def truncate(text)
+      text.to_s[0, MAX_TEXT_LENGTH]
+    end
+
+    def config
+      Ragify.configuration
+    end
+  end
+end

data/lib/ragify/http_client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Ragify
+  # Minimal HTTP client using Net::HTTP. No external dependencies.
+  class HttpClient
+    class ApiError < Error; end
+
+    def post_json(url, body:, timeout: 30)
+      uri = URI.parse(url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.open_timeout = 10
+      http.read_timeout = timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{Ragify.configuration.openai_api_key!}"
+      request.body = JSON.generate(body)
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ApiError, "OpenAI API error #{response.code}: #{response.body}"
+      end
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/ragify/search.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ragify
+  # Semantic vector search against an Embeddable model.
+  #
+  #   Search.new(FaqEntry).call("how does cashback work?")
+  #   # => [{ record: #<FaqEntry>, content: "...", similarity: 0.87 }, ...]
+  #
+  class Search
+    def initialize(model)
+      @model = model
+    end
+
+    def call(query, limit: nil, threshold: nil)
+      limit ||= config.search_limit
+      threshold ||= config.similarity_threshold
+
+      embedding = EmbeddingClient.new.generate(query)
+      return [] if embedding.nil?
+
+      set_ivfflat_probes
+
+      results = @model
+                  .with_embedding
+                  .nearest_neighbors(:embedding, embedding, distance: "cosine")
+                  .limit(limit * 2)
+                  .to_a
+
+      results
+        .select { |record| (1 - record.neighbor_distance) >= threshold }
+        .first(limit)
+        .map { |record| format_result(record) }
+    end
+
+    private
+
+    def set_ivfflat_probes
+      @model.connection.execute("SET ivfflat.probes = #{config.ivfflat_probes}")
+    end
+
+    def format_result(record)
+      similarity = (1 - record.neighbor_distance).round(4)
+      content = record.ragify_text
+
+      { record: record, content: content, similarity: similarity }
+    end
+
+    def config
+      Ragify.configuration
+    end
+  end
+end

data/lib/ragify/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ragify
+  VERSION = "0.1.0"
+end

data/lib/ragify.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "ragify/version"
+require_relative "ragify/configuration"
+require_relative "ragify/http_client"
+require_relative "ragify/embedding_client"
+require_relative "ragify/embeddable"
+require_relative "ragify/search"
+require_relative "ragify/chat"
+
+module Ragify
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def chat(query, context_model:, system_prompt: nil, **options)
+      Chat.new(context_model: context_model, system_prompt: system_prompt, **options).call(query)
+    end
+
+    def embed(text)
+      EmbeddingClient.new.generate(text)
+    end
+
+    def embed_batch(texts)
+      EmbeddingClient.new.generate_batch(texts)
+    end
+  end
+end

data/sig/ragify.rbs

@@ -0,0 +1,4 @@
+module Ragify
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: ragify
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pavel Skripin
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: neighbor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Add semantic search and AI-powered chat to any ActiveRecord model. Uses
+  pgvector for vector storage, OpenAI for embeddings, and your existing PostgreSQL
+  database.
+email:
+- skripin.pavel@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/generators/ragify/install_generator.rb
+- lib/generators/ragify/templates/add_embedding_migration.rb.erb
+- lib/ragify.rb
+- lib/ragify/chat.rb
+- lib/ragify/configuration.rb
+- lib/ragify/embeddable.rb
+- lib/ragify/embedding_client.rb
+- lib/ragify/http_client.rb
+- lib/ragify/search.rb
+- lib/ragify/version.rb
+- sig/ragify.rbs
+homepage: https://github.com/pashgo/ragify
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pashgo/ragify
+  source_code_uri: https://github.com/pashgo/ragify
+  changelog_uri: https://github.com/pashgo/ragify/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: RAG (Retrieval-Augmented Generation) for Rails with pgvector and OpenAI
+test_files: []