rails_ai_kit 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f5b6bc37b278c3ccd429b8b37a24256b89675b56b2d0ffad092d55a6b2a93ba
-  data.tar.gz: f876cc97ad7180007ad9e57481474232c3695e4538e59d820b94b365cc52def9
+  metadata.gz: 9a208aebef365d1747565891023f45d9211b447dc301c8168ea2ae676b0b83c2
+  data.tar.gz: ed938882ac92300a9e9f06b12dc0892d4116bfd8148e9e3d0571c5af9dbd0479
 SHA512:
-  metadata.gz: fddc5b46a839156459abc6ba82419329d66aeca703b76151663a9b66296e0d9867467422ce71dd067f998e99c22639eb8fabc558e5ea07f34c4e697faf8694ca
-  data.tar.gz: 7a1420f049a63341d5783b20e08c7948ac4347c51a65ebfe71c6691f5f88ae9507174b16ccf1e42648c9ebd2dcbfc37aa7235ef378a99a63da525977bae016be
+  metadata.gz: fb31d8dc780086de7f673ccf1e3a13f6e7911850b4e93ed076508fc9c077df347381cfb7609866146babbfcd5e25b4e88c3590c68700965a19155fdb826f373d
+  data.tar.gz: fc1256d2d9525db8a6b7cddea733e6d6b3818a23ce3d13233f4b2dfd5f796427c1c51e2dbf5eb5c684ef7c7a74fff18ffad3bcba865351005bb26829215f2080

data/README.md

@@ -1,41 +1,55 @@
+<div align="center">
+  <img src="logo.png" alt="Rails AI Kit" width="160" />
+</div>
+
 # Rails AI Kit
 
-A Rails gem that adds a **classification layer on top of [pgvector](https://github.com/pgvector/pgvector)**. Instead of building custom ML or calling LLMs every time, use vector similarity to classify data: support tickets, content moderation, ecommerce categories, document routing, and more.
+**AI-first toolkit for Rails** — embeddings, vector search, and classification without running your own ML or calling LLMs on every request.
 
-**Source:** [github.com/imrrohitt/rails_ai_kit](https://github.com/imrrohitt/rails_ai_kit)
+> Rails gem for vector-based text classification (pgvector), embeddings (OpenAI, Cohere), similarity search, and generators. Train labels with examples; classify on save or in batch.
 
-- **No ML training** – train labels with example texts and compare embeddings
-- **No LLM cost** – one-time embedding per piece of content; classification is nearest-neighbor in PostgreSQL
-- **Rails-friendly** – `vector_classify`, `Classifier.train`, `Classifier.classify`, `Article.similar_to("query")`
-- **Multi-provider embeddings** – pass API keys for OpenAI, Cohere, or your own provider
+[![Ruby](https://img.shields.io/badge/Ruby-3.0+-red.svg)](https://rubygems.org/gems/rails_ai_kit)
+[![Rails](https://img.shields.io/badge/Rails-6.0+-blue.svg)](https://rubyonrails.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-## Architecture
+---
 
-```
-Your Rails App
-      │
-      ▼
-Rails AI Kit (classification + indexing + similarity)
-      │
-      ▼
-pgvector (PostgreSQL)
-      │
-      ▼
-vector similarity search → predicted label
-```
+### Overview
+
+| | |
+|:---|:---|
+| **Rails-native** | Generators, ActiveRecord integration, single config file |
+| **Vector-ready** | [pgvector](https://github.com/pgvector/pgvector) with OpenAI or Cohere embeddings |
+| **Modular** | Use only the features you need; add more as the gem evolves |
+
+**[Source code](https://github.com/imrrohitt/rails_ai_kit)** · **[RubyGems](https://rubygems.org/gems/rails_ai_kit)**
+
+---
+
+## Features
 
-The gem does **not** store your application data. You store data in your own PostgreSQL tables with pgvector. The gem provides:
+Rails AI Kit is organized around **features**. Each is optional and self-contained.
 
-- Classification logic (label training, classify by similarity)
-- Indexing helpers (migrations for vector columns and label table)
-- Similarity search (`similar_to`)
-- Filtering (standard `where(label: "sports")`)
+### Classifier
+
+Vector-based text classification: route support tickets, moderate content, tag articles, or categorize documents. No ML training — you provide example texts per label; classification is nearest-neighbor in PostgreSQL.
+
+- Train labels with examples → one vector per label  
+- Auto-classify on save (embed + compare → `label`, `confidence_score`)  
+- Similarity search: `Model.similar_to("query", limit: 5)`  
+- Batch classify for backfills or background jobs  
+
+*Requires pgvector, an embedding API (OpenAI/Cohere), and the install + vector_columns generators.*
+
+---
 
 ## Requirements
 
 - Rails 6+
-- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) extension
-- An embedding API (OpenAI or Cohere) and API key
+- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) (for Classifier and vector features)
+- An embedding API key (OpenAI or Cohere) for features that use embeddings
+
+---
 
 ## Installation
 
@@ -51,16 +65,16 @@ Then:
 bundle install
 ```
 
-### 1. Enable pgvector and create the labels table
+### 1. Install (pgvector + labels table)
 
-The gem needs one internal table to store **label embeddings** (one vector per label per classifier):
+For the **Classifier** feature, the gem needs pgvector and one internal table for label embeddings:
 
 ```bash
 rails g rails_ai_kit:install
 rails db:migrate
 ```
 
-### 2. Configure embedding provider and API keys
+### 2. Configure
 
 In `config/initializers/rails_ai_kit.rb` (create the file):
 
@@ -69,7 +83,6 @@ RailsAiKit.configure do |config|
   config.embedding_provider = :openai   # or :cohere
   config.embedding_dimensions = 1536   # 1536 for OpenAI text-embedding-3-small
 
-  # Pass API keys for the provider(s) you use
   config.api_keys = {
     openai: ENV["OPENAI_API_KEY"],
     cohere: ENV["COHERE_API_KEY"]
@@ -81,9 +94,9 @@ end
 
 Use environment variables or Rails credentials; do not commit raw API keys.
 
-### 3. Add vector columns to your model
+### 3. Add vector columns (for Classifier)
 
-For a new or existing table (e.g. `articles` with a `content` column):
+For models you want to classify (e.g. `articles` with a `content` column):
 
 ```bash
 rails g rails_ai_kit:vector_columns Article content
@@ -92,9 +105,23 @@ rails db:migrate
 
 This adds `embedding` (vector), `label` (string), and `confidence_score` (float).
 
+---
+
 ## Usage
 
-### Declare vector classification on a model
+### Embeddings (general)
+
+Use embeddings anywhere in your app:
+
+```ruby
+RailsAiKit.embed("some text")                    # => array of floats
+RailsAiKit.embedding.embed("text")               # same
+RailsAiKit.embedding.embed_batch(["a", "b"])     # batch
+```
+
+### Classifier feature
+
+#### Declare classification on a model
 
 ```ruby
 class Article < ApplicationRecord
@@ -107,55 +134,43 @@ On save, the gem will:
 
 1. Generate an embedding for `content`
 2. Store it in `embedding`
-3. Run classification (nearest label vector) and set `label` and `confidence_score`
-
-Example:
-
-```ruby
-article = Article.create!(content: "Apple released a new iPhone")
-article.label            # => "technology"
-article.confidence_score # => 0.91
-```
+3. Compare to trained label vectors and set `label` and `confidence_score`
 
-### Train labels with examples
+#### Train labels first
 
-Before classifying, train each label with example texts so the gem can build a label vector (average of example embeddings):
+Before classifying, train each label with example texts:
 
 ```ruby
-classifier = RailsAiKit.classifier("Article")  # or use default
+c = RailsAiKit.classifier("Article")
 
-classifier.train("sports", examples: [
+c.train("sports", examples: [
   "football match",
   "cricket tournament",
   "Olympic gold medal"
 ])
-
-classifier.train("politics", examples: [
-  "election results",
-  "parliament debate"
-])
-
-classifier.train("technology", examples: [
-  "new iPhone launch",
-  "AI software update"
-])
+c.train("politics", examples: ["election results", "parliament debate"])
+c.train("technology", examples: ["new iPhone launch", "AI software update"])
 ```
 
-You can use the default classifier name or pass a custom one:
+#### Create records
 
 ```ruby
-RailsAiKit.classifier("Article").train("sports", examples: [...])
-RailsAiKit.classifier.train("sports", examples: [...])  # default classifier
+article = Article.create!(content: "Apple released a new iPhone")
+article.label            # => "technology"
+article.confidence_score # => 0.91
 ```
 
-### Classify text without saving
+#### Classify without saving
 
 ```ruby
-result = RailsAiKit.classifier("Article").classify("India won the cricket match")
+RailsAiKit.classifier("Article").classify("India won the cricket match")
 # => { label: "sports", confidence: 0.91, distance: 0.09 }
+
+RailsAiKit.classifier("Article").classify_by_embedding(article.embedding)
+# => { label: "technology", confidence: 0.91, distance: 0.09 }
 ```
 
-### Batch classification
+#### Batch classification
 
 ```ruby
 records = Article.where(label: nil).limit(100)
@@ -164,26 +179,24 @@ RailsAiKit.classifier("Article").batch_classify(records,
   label_attribute: :label,
   confidence_attribute: :confidence_score
 )
-# Optionally save: records.each(&:save!)
+# Optionally: records.each(&:save!)
 ```
 
-### Filtering
-
-Use normal ActiveRecord scopes:
+#### Similarity search
 
 ```ruby
-Article.where(label: "sports")
-Article.where("confidence_score >= ?", 0.8)
+Article.similar_to("new iPhone launch", limit: 5)
 ```
 
-### Similarity search
-
-Find records similar to a piece of text (embeds the query, then nearest-neighbor search):
+#### Filtering
 
 ```ruby
-Article.similar_to("new iPhone launch", limit: 5)
+Article.where(label: "sports")
+Article.where("confidence_score >= ?", 0.8)
 ```
 
+---
+
 ## Example: Support ticket routing
 
 ```ruby
@@ -195,16 +208,18 @@ class SupportTicket < ApplicationRecord
 end
 
 # Train once
-classifier = RailsAiKit.classifier("SupportTicket")
-classifier.train("billing", examples: ["My payment failed", "Refund request", "Invoice issue"])
-classifier.train("technical", examples: ["App crashed", "Login not working", "Error message"])
-classifier.train("account", examples: ["Change email", "Close my account", "Password reset"])
+c = RailsAiKit.classifier("SupportTicket")
+c.train("billing", examples: ["My payment failed", "Refund request", "Invoice issue"])
+c.train("technical", examples: ["App crashed", "Login not working", "Error message"])
+c.train("account", examples: ["Change email", "Close my account", "Password reset"])
 
 # Incoming ticket
 ticket = SupportTicket.create!(message: "My payment failed last night")
 ticket.label  # => "billing" → route to billing queue
 ```
 
+---
+
 ## Configuration reference
 
 | Option | Description | Default |
@@ -212,27 +227,33 @@ ticket.label  # => "billing" → route to billing queue
 | `embedding_provider` | `:openai` or `:cohere` | `:openai` |
 | `embedding_dimensions` | Vector size (must match provider) | `1536` |
 | `api_keys` | Hash of provider => API key | `{}` |
-| `default_classifier_name` | Name when no classifier given | `"default"` |
+| `default_classifier_name` | Classifier name when none given | `"default"` |
+
+---
 
 ## Generators
 
 | Generator | Purpose |
 |-----------|---------|
-| `rails g rails_ai_kit:install` | Migration: enable pgvector + create `rails_ai_kit_labels` |
-| `rails g rails_ai_kit:vector_columns ModelName content_column` | Migration: add `embedding`, `label`, `confidence_score` to a table |
+| `rails g rails_ai_kit:install` | Enable pgvector + create `rails_ai_kit_labels` (for Classifier) |
+| `rails g rails_ai_kit:vector_columns ModelName content_column` | Add `embedding`, `label`, `confidence_score` to a table |
 
-## How it works
+---
 
-1. **Label vectors** – Each label is represented by a vector (average of example embeddings). Stored in `rails_ai_kit_labels`.
-2. **Classification** – New content is embedded and compared to all label vectors with cosine distance. The nearest label wins; confidence is `1 - distance`.
-3. **Storage** – Your table holds the content, its embedding, the predicted label, and confidence. The gem only adds one table for label vectors.
+## How Classifier works
 
-## Future ideas
+1. **Label vectors** – Each label is a vector (average of example embeddings), stored in `rails_ai_kit_labels`.
+2. **Classification** – New content is embedded and compared to label vectors (cosine distance). Nearest label wins; confidence = `1 - distance`.
+3. **Storage** – Your table holds content, embedding, predicted label, and confidence. The gem adds one table for label vectors only.
 
-- Hierarchical labels (e.g. technology → mobile, laptops)
-- Confidence threshold (e.g. mark as "unknown" if &lt; 0.7)
-- Hybrid search (vector + keyword)
-- Incremental learning (add examples to improve labels over time)
+---
+
+## Roadmap
+
+- **Classifier:** hierarchical labels, confidence threshold, hybrid search, incremental learning
+- **More features** – additional AI capabilities as the gem evolves
+
+---
 
 ## Development
 
@@ -243,21 +264,26 @@ bundle exec rake install
 
 Run tests (when added) with `bundle exec rspec` or `bundle exec rake test`.
 
+---
+
 ## License
 
 MIT.
 
+---
+
 ## How it’s built
 
-- **Configuration** (`lib/rails_ai_kit/configuration.rb`) – Embedding provider, dimensions, and API keys (e.g. `api_keys[:openai]`).
-- **Embedding providers** (`lib/rails_ai_kit/embedding_providers/`) – Base class plus OpenAI and Cohere. Each implements `embed(text)` and `embed_batch(texts)` using the provider API.
-- **EmbeddingService** – Wraps the configured provider and API key so `RailsAiKit.embedding.embed(text)` works without passing keys every time.
-- **LabelRecord** – ActiveRecord model for `rails_ai_kit_labels` (classifier_name, label_name, embedding). Uses Neighbor’s `has_neighbors :embedding` for similarity.
-- **Classifier** – Trains labels by averaging example embeddings and storing them; classifies by nearest-neighbor (cosine) against those label vectors. Supports `classify(text)`, `classify_by_embedding(vector)`, and `batch_classify(records)`.
-- **VectorClassify** – Concern that adds the `vector_classify` macro: `has_neighbors` on the embedding column, a before_save that embeds the source column and runs `classify_by_embedding`, and a `similar_to(query_text)` scope that embeds the query and runs nearest-neighbor search.
-- **Generators** – `rails_ai_kit:install` creates the labels table migration; `rails_ai_kit:vector_columns` adds embedding/label/confidence_score to a given table.
+- **Configuration** – Embedding provider, dimensions, API keys.
+- **Embedding providers** – Base + OpenAI and Cohere (`embed`, `embed_batch`).
+- **EmbeddingService** – `RailsAiKit.embedding` / `RailsAiKit.embed(text)`.
+- **Classifier** – Label training, `classify`, `classify_by_embedding`, `batch_classify`; uses `rails_ai_kit_labels` + Neighbor for similarity.
+- **VectorClassify** – ActiveRecord concern: `vector_classify` macro, `similar_to` scope.
+- **Generators** – Install (labels table), vector_columns (embedding/label/confidence on a model).
+
+---
 
 ## Related
 
-- [pgvector](https://github.com/pgvector/pgvector) – Open-source vector similarity search for Postgres
+- [pgvector](https://github.com/pgvector/pgvector) – Vector similarity search for Postgres
 - [Neighbor](https://github.com/ankane/neighbor) – Nearest neighbor search for Rails (used by this gem)

data/lib/generators/rails_ai_kit/vector_columns_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require "rails/generators"
-require "rails/generators/active_record/migration/migration_generator"
+require "rails/generators/active_record/migration"
 
 module RailsAiKit
   module Generators
     class VectorColumnsGenerator < Rails::Generators::NamedBase
-      source_root File.expand_path("templates", __dir__)
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("vector_columns/templates", __dir__)
 
       desc "Adds embedding, label, and confidence_score columns to an existing table for vector_classify"
 
@@ -16,9 +18,9 @@ module RailsAiKit
       class_option :embedding_dimensions, type: :numeric, default: 1536,
                    desc: "Vector dimensions (must match your embedding provider)"
 
-      def create_migration
+      def add_vector_columns_migration
         migration_template "add_vector_columns.rb",
-                          "db/migrate/#{migration_timestamp}_add_rails_ai_kit_vector_columns_to_#{table_name}.rb"
+                          "db/migrate/add_rails_ai_kit_vector_columns_to_#{table_name}.rb"
       end
 
       private
@@ -27,10 +29,6 @@ module RailsAiKit
         name.underscore.pluralize
       end
 
-      def migration_timestamp
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
-      end
-
       def dimensions
         options[:embedding_dimensions] || (defined?(RailsAiKit) && RailsAiKit.configuration.embedding_dimensions) || 1536
       end

data/lib/rails_ai_kit/classifier.rb

@@ -6,7 +6,13 @@ module RailsAiKit
   class Classifier
     attr_reader :classifier_name
 
-    def initialize(classifier_name: nil)
+    def initialize(classifier_name: nil, **kwargs)
+      if kwargs.any?
+        raise ArgumentError,
+              "Classifier accepts only classifier_name: (optional). " \
+              "Labels are trained with .train(label_name, examples: [...]). " \
+              "Unknown: #{kwargs.keys.join(', ')}"
+      end
       @classifier_name = classifier_name || RailsAiKit.configuration.default_classifier_name
     end
 

data/lib/rails_ai_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiKit
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/rails_ai_kit.rb

@@ -4,7 +4,7 @@ require_relative "rails_ai_kit/version"
 require_relative "rails_ai_kit/configuration"
 
 module RailsAiKit
-  class Error < StandardError; end
+  class Error < StandardError; end 
 end
 
 require_relative "rails_ai_kit/embedding_providers/base"
@@ -36,4 +36,9 @@ module RailsAiKit
   def self.classifier(classifier_name = nil)
     Classifier.new(classifier_name: classifier_name)
   end
+
+  # Convenience: embed a single text. Same as RailsAiKit.embedding.embed(text).
+  def self.embed(text)
+    embedding.embed(text)
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rails_ai_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Rails AI Kit Contributors
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -66,11 +65,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
-description: 'Rails AI Kit provides ready-made tools to classify data using vector
-  similarity: label training, auto/batch classification, similarity search, and filtering—without
-  ML training or LLM calls.'
+description: 'Rails AI Kit provides AI building blocks for Rails apps: embeddings
+  (OpenAI, Cohere), vector-based classification, similarity search, and generators.
+  Start with the Classifier feature; more capabilities as the gem grows.'
 email:
-- rohit.kushwaha@w3villa.com
+- imrohitkushwaha2002@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -98,7 +97,6 @@ metadata:
   homepage_uri: https://github.com/imrrohitt/rails_ai_kit
   source_code_uri: https://github.com/imrrohitt/rails_ai_kit
   changelog_uri: https://github.com/imrrohitt/rails_ai_kit/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -113,8 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Vector-based classification layer on top of pgvector for Rails
+summary: 'AI-first toolkit for Rails: embeddings, vector search, and classification'
 test_files: []