kakugosearch-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d82d1ce3c7b5c8abe1fcfb8999aad36314d95bc4313e41ef05b505cb0448460c
+  data.tar.gz: 33a03799ff363d9edb1e030c258172fbbe2dda0dd2ed8dc77da45a5e92508fce
+SHA512:
+  metadata.gz: e0860bf171a2bfb0a8a43b69fd920dbd17d66f4d99c3754519ee05615d78e0d0f89eef58fe7e602b1b3a13f2a3d8259c55b55cf9b0533a0768184d27327f0546
+  data.tar.gz: 35a86afd4f05e692eb2827602605761097b6189c59ca7db13216e50e6c04bd73ef7397433556ad30e16452ab929518796e7ca12df6080557a1797a802881972e

data/README.md

@@ -0,0 +1,81 @@
+# kakugosearch-rails
+
+Rails integration for [KakugoSearch](https://github.com/your-org/kakugosearch) — a lightweight, AI-enhanced full-text search engine written in Rust.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "kakugosearch-rails"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+# config/initializers/kakugosearch.rb
+KakugoSearch.configure do |config|
+  config.url     = "http://localhost:7700"          # KakugoSearch server URL
+  config.api_key = ENV["KAKUGOSEARCH_AI_API_KEY"]   # optional, for AI reranking
+end
+```
+
+## Usage
+
+Include `KakugoSearch::Searchable` in any ActiveRecord model and declare which fields to index:
+
+```ruby
+class Article < ApplicationRecord
+  include KakugoSearch::Searchable
+
+  kakugosearch_index(
+    index:  "articles",          # index name (defaults to table_name)
+    fields: {
+      title: :title,             # KakugoSearch field => AR attribute/method
+      body:  :content,
+      url:   :permalink,
+    }
+  )
+end
+```
+
+Records are automatically indexed on `save` and removed from the index on `destroy`.
+
+### Searching
+
+```ruby
+# Basic search
+results = Article.kakugosearch("rust programming")
+
+# With options
+results = Article.kakugosearch("machine learning",
+  limit:     10,
+  ai:        true,    # enable AI reranking
+  ai_weight: 0.5      # blend of BM25 vs AI (0.0–1.0)
+)
+```
+
+Returns ActiveRecord objects in ranked order.
+
+## Behaviour Notes
+
+- **Synchronous** — indexing happens inline with `save`/`destroy`. Wrap in `after_commit` if you need post-transaction indexing.
+- **Errors on indexing are logged, not raised** — a failed HTTP call to KakugoSearch will not break your model save.
+- **Errors on search do raise** — a `KakugoSearch::Error` is raised so callers can handle it.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/kakugosearch/client.rb

@@ -0,0 +1,44 @@
+require "net/http"
+require "json"
+require "uri"
+
+module KakugoSearch
+  class Client
+    def initialize(config = KakugoSearch.configuration)
+      @config = config
+    end
+
+    # POST /indexes/{index}/documents
+    def index_documents(index, docs)
+      uri = URI("#{@config.url}/indexes/#{index}/documents")
+      request(Net::HTTP::Post, uri, docs)
+    end
+
+    # DELETE /indexes/{index}/documents/{id}
+    def delete_document(index, id)
+      uri = URI("#{@config.url}/indexes/#{index}/documents/#{id}")
+      request(Net::HTTP::Delete, uri)
+    end
+
+    # GET /indexes/{index}/search
+    def search(index, query, limit: 20, ai: false, ai_weight: 0.3)
+      params = URI.encode_www_form(q: query, limit: limit, ai: ai, ai_weight: ai_weight)
+      uri    = URI("#{@config.url}/indexes/#{index}/search?#{params}")
+      request(Net::HTTP::Get, uri)
+    end
+
+    private
+
+    def request(method_class, uri, body = nil)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        req = method_class.new(uri)
+        req["Content-Type"] = "application/json"
+        req["Accept"]       = "application/json"
+        req["Authorization"] = "Bearer #{@config.api_key}" if @config.api_key
+        req.body = body.to_json if body
+        response = http.request(req)
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/kakugosearch/configuration.rb

@@ -0,0 +1,11 @@
+module KakugoSearch
+  class Configuration
+    attr_accessor :url, :api_key, :default_index
+
+    def initialize
+      @url           = "http://localhost:7700"
+      @api_key       = ENV["KAKUGOSEARCH_AI_API_KEY"]
+      @default_index = nil
+    end
+  end
+end

data/lib/kakugosearch/railtie.rb

@@ -0,0 +1,13 @@
+require "rails/railtie"
+
+module KakugoSearch
+  class Railtie < Rails::Railtie
+    initializer "kakugosearch.include_searchable" do
+      ActiveSupport.on_load(:active_record) do
+        # Searchable is opt-in; Railtie just ensures it's available without
+        # manual require in application code.
+        require "kakugosearch/searchable"
+      end
+    end
+  end
+end

data/lib/kakugosearch/searchable.rb

@@ -0,0 +1,61 @@
+require "active_support/concern"
+
+module KakugoSearch
+  module Searchable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_kakugosearch_index_name, instance_writer: false
+      class_attribute :_kakugosearch_fields,      instance_writer: false
+    end
+
+    class_methods do
+      # kakugosearch_index index: "articles", fields: { title: :title, body: :content }
+      def kakugosearch_index(index: nil, fields: {})
+        self._kakugosearch_index_name = index || table_name
+        self._kakugosearch_fields     = fields
+
+        after_save    :kakugosearch_index_document
+        after_destroy :kakugosearch_delete_document
+      end
+
+      # Article.kakugosearch("rust programming", limit: 10, ai: false)
+      def kakugosearch(query, limit: 20, ai: false, ai_weight: 0.3)
+        result = KakugoSearch.client.search(
+          _kakugosearch_index_name, query,
+          limit: limit, ai: ai, ai_weight: ai_weight
+        )
+
+        hits = Array(result["hits"])
+        ids  = hits.map { |h| h["id"] }
+        return none if ids.empty?
+
+        # Preserve ranked order
+        records_by_id = where(id: ids).index_by { |r| r.id.to_s }
+        ids.filter_map { |id| records_by_id[id.to_s] }
+      rescue => e
+        raise KakugoSearch::Error, "Search failed: #{e.message}"
+      end
+    end
+
+    private
+
+    def kakugosearch_index_document
+      doc = { id: id.to_s }
+      self.class._kakugosearch_fields.each do |field, method_name|
+        doc[field] = public_send(method_name)
+      end
+      KakugoSearch.client.index_documents(self.class._kakugosearch_index_name, [doc])
+    rescue => e
+      logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
+      logger.error("[KakugoSearch] Failed to index #{self.class.name}##{id}: #{e.message}")
+    end
+
+    def kakugosearch_delete_document
+      KakugoSearch.client.delete_document(self.class._kakugosearch_index_name, id.to_s)
+    rescue => e
+      logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
+      logger.error("[KakugoSearch] Failed to delete #{self.class.name}##{id}: #{e.message}")
+    end
+  end
+end

data/lib/kakugosearch/version.rb

@@ -0,0 +1,3 @@
+module KakugoSearch
+  VERSION = "0.1.0"
+end

data/lib/kakugosearch.rb

@@ -0,0 +1,29 @@
+require "kakugosearch/version"
+require "kakugosearch/configuration"
+require "kakugosearch/client"
+
+module KakugoSearch
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Reset memoized client when config changes (useful in tests)
+    def reset!
+      @configuration = nil
+      @client        = nil
+    end
+  end
+end
+
+require "kakugosearch/railtie" if defined?(Rails)

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: kakugosearch-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Allan Farinas
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Drop-in ActiveRecord concern that keeps KakugoSearch indexes in sync
+  with your models via save/destroy callbacks, plus a search class method.
+email:
+- hello@allanfarinas.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/kakugosearch.rb
+- lib/kakugosearch/client.rb
+- lib/kakugosearch/configuration.rb
+- lib/kakugosearch/railtie.rb
+- lib/kakugosearch/searchable.rb
+- lib/kakugosearch/version.rb
+homepage: https://github.com/alpha-san/kakugosearch-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alpha-san/kakugosearch-rails
+  source_code_uri: https://github.com/alpha-san/kakugosearch-rails
+  changelog_uri: https://github.com/alpha-san/kakugosearch-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/alpha-san/kakugosearch-rails/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails integration for the KakugoSearch AI-enhanced search engine
+test_files: []