ragify 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a8b50afa93cb29e25eda8a6e6c1bc902ed50b106bbb1b18db1c607672c92d86
-  data.tar.gz: 02f99522340f1a8c2738c6fbc12c45e50fbfb5de4db9771580881a13385b6c11
+  metadata.gz: 1fadf58c11fd46229633ce0bdb6f9b06826bd9a8f03925c33e8139817ca424de
+  data.tar.gz: 5521897995ef1d73849a737b6dfed79277d34d41cf640c9243299d3c1d2bf775
 SHA512:
-  metadata.gz: 15c94ec278c69c2615c32ae88bd84bece4fec6d1cde2d524cebcd5ddc512152a15c4e2c4b138036baf3ab978940ae3412e4323342e6e10f89afa101896b4f58b
-  data.tar.gz: 280a443ad84ed106454fbad4ac76b6ea0604ce6c80f2e74af02d350eda1c5a9c875db547dd28ab5cdc5372136a62432cc6bc9d41ccd1b03940abae308a1e4a34
+  metadata.gz: 0f443e79c19bbba5fbb4a5698656ebc0cfca179907cc09661c3d24d73cf1005bc137dc5479eebcb45fe8bab12fb4fd12443579314ac08154f38b448084e32e0e
+  data.tar.gz: 366a12eb4674d988bc0dc7f26d33e8566d900778791921d38622f358d95ea027167d6098e4f0708ab15adc6a3be9c5661bb8e228a335c5ccefae7545aa5ac2ad

data/lib/generators/ragify/install_generator.rb

@@ -26,14 +26,14 @@ module Ragify
       say "  2. Add to your model:"
       say "     class #{model_name} < ApplicationRecord"
       say "       include Ragify::Embeddable"
-      say '       ragify_content { |r| "#{r.question} #{r.answer}" }'
+      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 "     #{model_name}.semantic_search(\"your query\")"
       say ""
     end
 

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

@@ -3,6 +3,7 @@ class AddRagifyEmbeddingTo<%= table_name.camelize %> < ActiveRecord::Migration[<
     enable_extension "vector" unless extension_enabled?("vector")
 
     add_column :<%= table_name %>, :embedding, :vector, limit: <%= dimensions %>
+    add_column :<%= table_name %>, :embedding_digest, :string
     add_index :<%= table_name %>, :embedding, using: :ivfflat, opclass: :vector_cosine_ops
   end
 end

data/lib/ragify/chat.rb

@@ -13,7 +13,7 @@ module Ragify
     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."
+                            "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
@@ -59,10 +59,10 @@ module Ragify
         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
+      user_content = if context.empty?
                        query
+                     else
+                       "Context:\n#{context}\n\n---\n\nQuestion: #{query}"
                      end
 
       messages << { role: "user", content: user_content }
@@ -71,11 +71,11 @@ module Ragify
 
     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)
+                                 model: config.chat_model,
+                                 messages: messages,
+                                 max_tokens: config.max_tokens,
+                                 temperature: config.temperature
+                               }, timeout: 60)
     end
 
     def config

data/lib/ragify/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "logger"
+require "digest"
+
 module Ragify
   class Configuration
     attr_accessor :openai_api_key,
@@ -11,7 +14,8 @@ module Ragify
                   :similarity_threshold,
                   :search_limit,
                   :ivfflat_probes,
-                  :logger
+                  :logger,
+                  :async
 
     def initialize
       @openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
@@ -23,12 +27,30 @@ module Ragify
       @similarity_threshold = 0.2
       @search_limit = 5
       @ivfflat_probes = 10
+      @async = false
       @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']")
+      openai_api_key || raise(
+        Error,
+        "Ragify: openai_api_key is not configured. " \
+        "Set via Ragify.configure { |c| c.openai_api_key = '...' } or ENV['OPENAI_API_KEY']"
+      )
+    end
+
+    def validate!
+      unless embedding_dimensions.is_a?(Integer) && embedding_dimensions.positive?
+        raise Error,
+              "embedding_dimensions must be a positive integer"
+      end
+      raise Error, "similarity_threshold must be between 0 and 1" unless (0..1).cover?(similarity_threshold.to_f)
+      raise Error, "search_limit must be positive" unless search_limit.to_i.positive?
+      raise Error, "ivfflat_probes must be positive" unless ivfflat_probes.to_i.positive?
+      raise Error, "max_tokens must be positive" unless max_tokens.to_i.positive?
+      raise Error, "temperature must be between 0 and 2" unless (0..2).cover?(temperature.to_f)
+
+      true
     end
   end
 end

data/lib/ragify/embeddable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "neighbor"
+require "digest"
 
 module Ragify
   # Include in ActiveRecord models to add vector embeddings and semantic search.
@@ -52,17 +54,22 @@ module Ragify
         Search.new(self).call(query, limit: limit, threshold: threshold)
       end
 
-      # Generate embeddings for all records (or a subset).
+      # Generate embeddings for all records using batch API.
       #
       #   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
+        find_each(batch_size: batch_size).each_slice(batch_size) do |batch|
+          texts = batch.map { |record| ragify_content_proc.call(record) }
+          embeddings = client.generate_batch(texts)
+
+          batch.each_with_index do |record, i|
+            next unless embeddings[i]
+
+            record.update_columns(embedding: embeddings[i], embedding_digest: Digest::SHA256.hexdigest(texts[i].to_s))
+          end
         end
       end
     end
@@ -78,13 +85,44 @@ module Ragify
       text = ragify_text
       return if text.blank?
 
+      if Ragify.configuration.async
+        ragify_async_embed
+      else
+        ragify_sync_embed(text)
+      end
+    end
+
+    def ragify_sync_embed(text)
       embedding = Ragify.embed(text)
-      update_column(:embedding, embedding) if embedding # rubocop:disable Rails/SkipsModelValidations
+      return unless embedding
+
+      update_columns(embedding: embedding, embedding_digest: Digest::SHA256.hexdigest(text.to_s))
+    end
+
+    # Override this method to use your own async job.
+    #
+    #   def ragify_async_embed
+    #     MyEmbeddingJob.perform_later(id)
+    #   end
+    #
+    def ragify_async_embed
+      Ragify.configuration.logger.warn(
+        "[Ragify] async=true but ragify_async_embed not overridden in #{self.class.name}. " \
+        "Override it to enqueue a background job."
+      )
     end
 
     def ragify_content_changed?
-      # Always regenerate — the content proc may depend on any attribute
-      true
+      text = ragify_text
+      return false if text.blank?
+
+      current_digest = Digest::SHA256.hexdigest(text.to_s)
+
+      if respond_to?(:embedding_digest) && embedding_digest.present?
+        current_digest != embedding_digest
+      else
+        true
+      end
     end
   end
 end

data/lib/ragify/embedding_client.rb

@@ -38,7 +38,9 @@ module Ragify
     private
 
     def request(input)
-      HttpClient.new.post_json(OPENAI_URL, body: { model: config.embedding_model, input: input })
+      body = { model: config.embedding_model, input: input }
+      body[:dimensions] = config.embedding_dimensions if config.embedding_dimensions
+      HttpClient.new.post_json(OPENAI_URL, body: body)
     end
 
     def truncate(text)

data/lib/ragify/http_client.rb

@@ -5,11 +5,34 @@ require "json"
 require "uri"
 
 module Ragify
-  # Minimal HTTP client using Net::HTTP. No external dependencies.
+  # Minimal HTTP client with retry/backoff. No external dependencies.
   class HttpClient
     class ApiError < Error; end
+    class RateLimitError < ApiError; end
+    class AuthenticationError < ApiError; end
+    class TimeoutError < ApiError; end
+
+    MAX_RETRIES = 3
+    BASE_BACKOFF = 1 # seconds
 
     def post_json(url, body:, timeout: 30)
+      retries = 0
+
+      begin
+        raw_request(url, body: body, timeout: timeout)
+      rescue RateLimitError, TimeoutError, Net::OpenTimeout, Net::ReadTimeout => e
+        retries += 1
+        if retries <= MAX_RETRIES
+          sleep(BASE_BACKOFF * (2**(retries - 1))) # exponential: 1s, 2s, 4s
+          retry
+        end
+        raise ApiError, "#{e.message} (after #{MAX_RETRIES} retries)"
+      end
+    end
+
+    private
+
+    def raw_request(url, body:, timeout:)
       uri = URI.parse(url)
 
       http = Net::HTTP.new(uri.host, uri.port)
@@ -24,11 +47,16 @@ module Ragify
 
       response = http.request(request)
 
-      unless response.is_a?(Net::HTTPSuccess)
-        raise ApiError, "OpenAI API error #{response.code}: #{response.body}"
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPTooManyRequests
+        raise RateLimitError, "Rate limited (429)"
+      when Net::HTTPUnauthorized
+        raise AuthenticationError, "Invalid API key (401)"
+      else
+        raise ApiError, "OpenAI API error #{response.code}: #{response.body.to_s[0, 200]}"
       end
-
-      JSON.parse(response.body)
     end
   end
 end

data/lib/ragify/search.rb

@@ -2,13 +2,14 @@
 
 module Ragify
   # Semantic vector search against an Embeddable model.
+  # Accepts any ActiveRecord scope, so you can pre-filter by tenant, status, etc.
   #
-  #   Search.new(FaqEntry).call("how does cashback work?")
-  #   # => [{ record: #<FaqEntry>, content: "...", similarity: 0.87 }, ...]
+  #   Search.new(FaqEntry.published).call("how does cashback work?")
+  #   Search.new(FaqEntry.where(tenant_id: 1)).call("refund policy")
   #
   class Search
-    def initialize(model)
-      @model = model
+    def initialize(scope)
+      @scope = scope
     end
 
     def call(query, limit: nil, threshold: nil)
@@ -20,11 +21,11 @@ module Ragify
 
       set_ivfflat_probes
 
-      results = @model
-                  .with_embedding
-                  .nearest_neighbors(:embedding, embedding, distance: "cosine")
-                  .limit(limit * 2)
-                  .to_a
+      results = @scope
+                .with_embedding
+                .nearest_neighbors(:embedding, embedding, distance: "cosine")
+                .limit(limit * 2)
+                .to_a
 
       results
         .select { |record| (1 - record.neighbor_distance) >= threshold }
@@ -35,7 +36,7 @@ module Ragify
     private
 
     def set_ivfflat_probes
-      @model.connection.execute("SET ivfflat.probes = #{config.ivfflat_probes}")
+      @scope.connection.execute("SET ivfflat.probes = #{config.ivfflat_probes}")
     end
 
     def format_result(record)

data/lib/ragify/version.rb

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

data/lib/ragify.rb

@@ -1,12 +1,6 @@
 # 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
@@ -22,8 +16,8 @@ module Ragify
       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)
+    def chat(query, context_model:, system_prompt: nil, **)
+      Chat.new(context_model: context_model, system_prompt: system_prompt, **).call(query)
     end
 
     def embed(text)
@@ -35,3 +29,10 @@ module Ragify
     end
   end
 end
+
+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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ragify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pavel Skripin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord