speaky 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 324621bdf6ab39e6bc0684802da3ab22ca135e84131ce203c013dfe4ecaf88ba
-  data.tar.gz: c4bcfaa3aaa8b4e01847a28b575e18e4c7ea71a28ef01e21ddf90df03a158ec8
+  metadata.gz: 24debd882e7071392c95c5a0f916fd0354f933ced5ce94f6a260e11c9766d5f9
+  data.tar.gz: 9e2238fb22c50493a97cde8799c645582ecd4f1527d7f8420adeed4296165479
 SHA512:
-  metadata.gz: cffab9177f8fa227a37fa8a863b2c3f27d0b9ceb21fca929939a38be44296b4afcc54100ac62bd68ae8584afda053e1b05bcf6d56ca09367489a1058e8934f9a
-  data.tar.gz: 93021aa4edae4c59dda48956c8929bc14f5961342aea042d712a241cd286eaf4664458c4b490b6eae2b073efeb8324d98e559ba66d80d456f1b08bbdbdde5047
+  metadata.gz: '009c0303f434bcf2e15fef4f047da10db442ef9ec1a1d4c691e411ddfe34abe3a27e9820ae685978b49e62fdfe0af0c8554bd637a5b19cb709b90d7afd7a1c75'
+  data.tar.gz: 411eeca77146779120e94f6f62e9e69bad488ca4f8ea4f4838bfc586e902411143487fdeb5ddb35e02f80366a34f777bc64c7b0e9030077ba2c9c3b3d6e72135

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2024 Gregorio Galante
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# Speaky
+
+**UNDER DEVELOPMENT**
+
+Store activerecord models in vector stores and query them with LLMs!
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'speaky'
+```
+
+Install the gem:
+
+```bash
+bundle install
+```
+
+Create a new configuration initializer:
+
+```ruby
+# config/initializers/speaky.rb
+
+Speaky.configure do |config|
+  # Set the LLM type to use for querying the vector store.
+  # - 'openai' -> require 'ruby-openai' gem
+  config.llm_type = 'openai'
+
+  # Set the LLM configuration options.
+  # - for 'openai' LLMs, view https://github.com/alexrudall/ruby-openai for configuration options
+  config.llm_config = {
+    access_token: 'YOUR_ACCESS_TOKEN',
+    organization_id: 'YOUR_ORGANIZATION_ID',
+  }
+
+  # Set the vector store type to use for storing model instances.
+  # - 'qdrant' -> require 'qdrant-ruby' gem
+  config.vectorstore_type = 'qdrant'
+
+  # Set the vector store configuration options.
+  # - for 'qdrant' vector stores, :url, :api_key, :collection_name are required
+  config.vectorstore_config = {
+    url: 'YOUR_URL',
+    api_key: 'YOUR_API_KEY',
+    collection_name: 'YOUR_COLLECTION_NAME',
+  }
+end
+```
+
+## Usage
+
+To use the gem, include the `Speaky::Concern` module in your ActiveRecord models that should be stored in the vector store:
+
+```ruby
+class MyModel < ApplicationRecord
+  include Speaky::Concern
+
+  def as_speaky
+    # This method should return a string representation of the model instance data that should be stored in the vector store. The default implementation is to call `to_json` on the model instance data.
+  end
+
+  # Add any callbacks that should update the model instance data in the vector store.
+  after_create :create_for_speaky
+  after_update :update_for_speaky
+  after_save :save_for_speaky
+  after_destroy :destroy_for_speaky
+end
+```
+
+To chat with the LLM, use the `Speaky.chat` method:
+
+```ruby
+# Using default prompt template
+Speaky.ask('What is the capital of France?')
+
+# Using custom prompt template
+Speaky.ask(
+  'What is the capital of France?',
+  template: 'You are a chatbot. Please answer the following question: {{question}} using this context: {{context}}.'
+)
+```
+
+## Development
+
+1. Clone the repo
+
+2. Install dependencies with `bundle install`
+
+3. Create your local `.env` file with `cp .env.example .env`
+
+4. Run the tests with `bundle exec rspec`
+
+### Publish a new version
+
+1. Update the version in `lib/speaky/version.rb`
+
+2. Run `ruby bin/publish`
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/speaky/concern.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+module Speaky
+  # This is a module that should be used as a Rails concern.
+  module Concern
+    extend ActiveSupport::Concern
+
+    def as_speaky
+      self.to_json
+    end
+
+    def create_for_speaky
+      begin
+        Speaky.vectorstore.add(self.id, self.as_speaky)
+      rescue StandardError => e
+        Rails.logger.error(e)
+        errors.add(:base, 'Failed to create for speaky')
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    def update_for_speaky
+      begin
+        Speaky.vectorstore.update(self.id, self.as_speaky)
+      rescue StandardError => e
+        Rails.logger.error(e)
+        errors.add(:base, 'Failed to update for speaky')
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    def destroy_for_speaky
+      begin
+        Speaky.vectorstore.remove(self.id)
+      rescue StandardError => e
+        Rails.logger.error(e)
+        errors.add(:base, 'Failed to destroy for speaky')
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    def save_for_speaky
+      ActiveRecord::Base.transaction do
+        if self.new_record?
+          create_for_speaky
+        else
+          update_for_speaky
+        end
+      end
+    end
+  end
+end

data/lib/speaky/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Speaky
+  # This is a class that stores the configuration of the gem.
+  class Config
+    # LLM configuration
+    attr_accessor :llm_type, :llm_config
+
+    # Vectorstore configuration
+    attr_accessor :vectorstore_type, :vectorstore_config
+
+    def initialize
+      @llm_type = 'openai'
+      @llm_config = {}
+
+      @vectorstore_type = 'qdrant'
+      @vectorstore_config = {}
+    end
+  end
+end

data/lib/speaky/llm_base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Speaky
+  class LlmBase
+    def initialize(config)
+      @config = config
+    end
+
+    def config
+      @config
+    end
+
+    def embed(text)
+      raise NotImplementedError
+    end
+
+    def chat(prompt)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/speaky/llm_openai.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "openai"
+
+module Speaky
+  class LlmOpenai < LlmBase
+    def initialize(config)
+      @config = config
+
+      # check if the access token is set
+      raise "Openai access token is not set" unless @config[:access_token]
+
+      # setup client
+      @client = OpenAI::Client.new(@config)
+
+      # setup embeddings params
+      # NOTE: This is a hardcoded value for now but can be made configurable in the future by passing it in the config
+      @embeddings_params = {
+        model: 'text-embedding-3-small',
+        dimensions: 1536
+      }
+
+      # setup chat params
+      # NOTE: This is a hardcoded value for now but can be made configurable in the future by passing it in the config
+      @chat_params = {
+        model: "gpt-3.5-turbo",
+        max_tokens: 1000
+      }
+    end
+
+    def embed(text)
+      params = @embeddings_params.merge({
+        input: text
+      })
+
+      response = @client.embeddings(parameters: params)
+      response["data"].find { |d| d["object"] == "embedding" }["embedding"]
+    end
+
+    def chat(prompt)
+      params = @chat_params.merge({
+        messages: [
+          {
+            role: "user",
+            content: prompt
+          }
+        ]
+      })
+
+      response = @client.chat(parameters: params)
+
+      response["choices"].first.dig("message", "content")
+    end
+  end
+end

data/lib/speaky/vectorstore_base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Speaky
+  class VectorstoreBase
+    def initialize(config)
+      @config = config
+    end
+
+    def config
+      @config
+    end
+
+    # Add a vector to the vectorstore.
+    # NOTE: If the vector already exists, it will be updated.
+    def add(id, data)
+      raise NotImplementedError
+    end
+
+    # Update a vector in the vectorstore.
+    # NOTE: If the vector does not exist, it will be added.
+    def update(id, data)
+      raise NotImplementedError
+    end
+
+    # Remove a vector from the vectorstore.
+    # NOTE: If the vector does not exist, it will be ignored.
+    def remove(id)
+      raise NotImplementedError
+    end
+
+    def query(question)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/speaky/vectorstore_faiss.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Speaky
+  class VectorstoreFaiss < VectorstoreBase
+    def initialize(config)
+      raise 'This class is not implemented yet.' # TEMP
+
+      @config = config
+
+      # check if the index path is set
+      raise ArgumentError, 'index_path is required' unless @config[:index_path]
+
+      # load index from index_path if exists
+      if File.exist?(@config[:index_path])
+        @index = Faiss::Index.load(@config[:index_path])
+      else
+        # create a new index
+        @index = Faiss::IndexFlatL2.new(768)
+        @index.save(@config[:index_path])
+      end
+    end
+
+    # TODO: Implement the other methods
+  end
+end

data/lib/speaky/vectorstore_qdrant.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'qdrant'
+
+module Speaky
+  class VectorstoreQdrant < VectorstoreBase
+    def initialize(config)
+      @config = config
+
+      # check if required fields are set
+      raise ArgumentError, 'url is required' unless @config[:url]
+      raise ArgumentError, 'api_key is required' unless @config[:api_key]
+      raise ArgumentError, 'collection_name is required' unless @config[:collection_name]
+
+      # setup client
+      @client = Qdrant::Client.new(
+        url: @config[:url],
+        api_key: @config[:api_key]
+      )
+
+      # create collection if it doesn't exist
+      collections_get = @client.collections.get(collection_name: @config[:collection_name])
+      if !collections_get || collections_get.dig('status') != 'ok'
+        collections_create = @client.collections.create(
+          collection_name: @config[:collection_name],
+          vectors: {
+            distance: "Cosine",
+            size: 1536
+          }
+        )
+        if !collections_create || collections_create.dig('status') != 'ok'
+          raise 'Failed to create collection'
+        end
+      end
+
+      # create index for field "id" in collection
+      collections_create_index = @client.collections.create_index(collection_name: @config[:collection_name], field_name: 'id', field_schema: 'keyword')
+      if !collections_create_index || collections_create_index.dig('status') != 'ok'
+        raise 'Failed to create index for field "id" on collection'
+      end
+    end
+
+    def add(id, data)
+      embeddings = Speaky.llm.embed(data)
+
+      points_upsert = @client.points.upsert(
+        collection_name: @config[:collection_name],
+        points: [
+          {
+            id: id,
+            vector: embeddings,
+            payload: {
+              content: data
+            }
+          }
+        ],
+        wait: true
+      )
+
+      if !points_upsert || points_upsert.dig('status') != 'ok'
+        raise 'Failed to add vector'
+      end
+
+      true
+    end
+
+    def update(id, data)
+      add(id, data)
+    end
+
+    def remove(id)
+      points_delete = @client.points.delete(
+        collection_name: @config[:collection_name],
+        points: [id],
+      )
+
+      if !points_delete || points_delete.dig('status') != 'ok'
+        raise 'Failed to remove vector'
+      end
+
+      true
+    end
+
+    def query(question)
+      embeddings = Speaky.llm.embed(question)
+
+      points_search = @client.points.search(
+        collection_name: @config[:collection_name],
+        limit: 1,
+        vector: embeddings,
+        with_payload: true,
+        with_vector: false
+      )
+
+      if !points_search || points_search.dig('status') != 'ok'
+        raise 'Failed to search vectors'
+      end
+
+      points_search.dig('result').first.dig('payload', 'content')
+    end
+  end
+end

data/lib/speaky/version.rb

@@ -0,0 +1,3 @@
+module Speaky
+  VERSION = '0.1.2'
+end

data/lib/speaky.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "speaky/version"
+require "speaky/config"
+require "speaky/concern"
+
+require "speaky/llm_base"
+require "speaky/llm_openai"
+
+require "speaky/vectorstore_base"
+require "speaky/vectorstore_qdrant"
+require "speaky/vectorstore_faiss"
+
+module Speaky
+  class << self
+    # This is a class method that returns a new instance of Config
+    # if @config is nil. If it is not nil, it returns the existing
+    # instance of Config.
+    #
+    # Example of usage:
+    # Speaky.config.some_value
+    def config
+      @config ||= Config.new
+    end
+
+    # This is a method that takes a block and yields the config
+    # instance to the block.
+    #
+    # Example of usage:
+    # Speaky.configure do |config|
+    #  config.some_value = "some value"
+    # end
+    def configure
+      yield config
+    end
+
+    # This is a method that returns an instance of VectorstoreBase class.
+    #
+    # Example of usage:
+    # Speaky.vectorstore.method_name
+    def vectorstore
+      return @vectorstore if defined?(@vectorstore) && @vectorstore
+
+      case config.vectorstore_type
+      when "faiss"
+        @vectorstore = VectorstoreFaiss.new(config.vectorstore_config)
+      when "qdrant"
+        @vectorstore = VectorstoreQdrant.new(config.vectorstore_config)
+      else
+        raise "Invalid vectorstore type"
+      end
+    end
+
+    # This is a method that returns an instance of LlmBase class.
+    #
+    # Example of usage:
+    # Speaky.llm.method_name
+    def llm
+      return @llm if defined?(@llm) && @llm
+
+      case config.llm_type
+      when "openai"
+        @llm = LlmOpenai.new(config.llm_config)
+      else
+        raise "Invalid llm type"
+      end
+    end
+
+    # This is a method that takes a question as an argument and returns
+    # the answer to the question from the LLM.
+    #
+    # Example of usage:
+    # Speaky.ask("What is the capital of France?")
+    def ask(question, template: nil, **other_params)
+      # load template
+      default_template = <<~TEMPLATE
+        You are an AI assistant. You are asked a question and you provide an answer.
+        Use the provided context to generate the answer to the question.
+
+        Context:
+        {{context}}
+
+        Question:
+        {{question}}
+      TEMPLATE
+      template ||= default_template
+
+      # load context
+      context = vectorstore.query(question)
+
+      # generate prompt
+      prompt = template.gsub("{{context}}", context).gsub("{{question}}", question)
+      other_params.each do |key, value|
+        prompt.gsub!("{{#{key}}}", value)
+      end
+
+      # ask the question
+      llm.chat(prompt)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: speaky
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Gregorio Galante
@@ -16,7 +16,18 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/speaky.rb
+- lib/speaky/concern.rb
+- lib/speaky/config.rb
+- lib/speaky/llm_base.rb
+- lib/speaky/llm_openai.rb
+- lib/speaky/vectorstore_base.rb
+- lib/speaky/vectorstore_faiss.rb
+- lib/speaky/vectorstore_qdrant.rb
+- lib/speaky/version.rb
 homepage: https://github.com/GAMS-Software/speaky
 licenses:
 - MIT