kakugosearch-rails
Rails integration for KakugoSearch — a lightweight, AI-enhanced full-text search engine written in Rust.
Installation
Add to your Gemfile:
gem "kakugosearch-rails"Then run:
bundle installConfiguration
# 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
endUsage
Include KakugoSearch::Searchable in any ActiveRecord model and declare which fields to index:
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,
}
)
endRecords are automatically indexed on save and removed from the index on destroy.
Searching
# 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 inafter_commitif 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::Erroris raised so callers can handle it.
Development
bundle install
bundle exec rspecLicense
MIT