spectre_ai 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ce184de05db051e8406fcd782ab084b745899cf914ac606a3a57b7201835325
+  data.tar.gz: b2adc0ef0d18ca87a9af0d5a1e3ca4273d2fad2d234a8f1f2cb9c3ca370723ae
+SHA512:
+  metadata.gz: cbfaa059e8432580a7fbda955ff66945a7e5b97fd76205feb1ae9f1934bf02bfe610741e56f43ecf8dc842fb600e3e1a913e5992044dc96b72a3c7feece87a3c
+  data.tar.gz: ea9ef3108a3f6550646cd698e13e9e32d97c0de7dcba1b4045d5b880095f078e7ef7520bea5c1515265853290610cf6859ce34497eee1dfbcee2a7f2852068bb

data/README.md

@@ -0,0 +1,307 @@
+# Spectre
+
+**Spectre** is a Ruby gem that makes it easy to AI-enable your Ruby on Rails application. Currently, Spectre focuses on helping developers create embeddings, perform vector-based searches, create chat completions, and manage dynamic prompts — ideal for applications that are featuring RAG (Retrieval-Augmented Generation), chatbots and dynamic prompts.
+
+## Compatibility
+
+| Feature                 | Compatibility |
+|-------------------------|---------------|
+| Foundation Models (LLM) | OpenAI        |
+| Embeddings              | OpenAI        |
+| Vector Searching        | MongoDB Atlas |
+| Prompt Templates        | OpenAI        |
+
+**💡 Note:** We will first prioritize adding support for additional foundation models (Claude, Cohere, LLaMA, etc.), then look to add support for more vector databases (Pgvector, Pinecone, etc.). If you're looking for something a bit more extensible, we highly recommend checking out [langchainrb](https://github.com/patterns-ai-core/langchainrb).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'spectre'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install spectre
+```
+
+## Usage
+
+### 1. Setup
+
+First, you’ll need to generate the initializer to configure your OpenAI API key. Run the following command to create the initializer:
+
+```bash
+rails generate spectre:install
+```
+
+This will create a file at `config/initializers/spectre.rb`, where you can set your OpenAI API key:
+
+```ruby
+Spectre.setup do |config|
+  config.api_key = 'your_openai_api_key'
+  config.llm_provider = :openai
+end
+```
+
+### 2. Enable Your Rails Model(s)
+
+#### For Embedding
+
+To use Spectre for generating embeddings in your Rails model, follow these steps:
+
+1. Include the Spectre module.
+2. Declare the model as embeddable.
+3. Define the embeddable fields.
+
+Here is an example of how to set this up in a model:
+
+```ruby
+class Model
+  include Mongoid::Document
+  include Spectre
+
+  spectre :embeddable
+  embeddable_field :message, :response, :category
+end
+```
+
+#### For Vector Searching (MongoDB Only)
+
+**Note:** Currently, the `Searchable` module is designed to work exclusively with Mongoid models. If you attempt to include it in a non-Mongoid model, an error will be raised. This ensures that vector-based searches, which rely on MongoDB's specific features, are only used in appropriate contexts.
+
+To enable vector-based search in your Rails model:
+
+1. Include the Spectre module.
+2. Declare the model as searchable.
+3. Configure search parameters.
+
+Use the following methods to configure the search path, index, and result fields:
+
+- **configure_spectre_search_path:** The path where the embeddings are stored.
+- **configure_spectre_search_index:** The index used for the vector search.
+- **configure_spectre_result_fields:** The fields to include in the search results.
+
+Here is an example of how to set this up in a model:
+
+```ruby
+class Model
+  include Mongoid::Document
+  include Spectre
+
+  spectre :searchable
+  configure_spectre_search_path 'embedding'
+  configure_spectre_search_index 'vector_index'
+  configure_spectre_result_fields({ "message" => 1, "response" => 1 })
+end
+```
+
+### 3. Create Embeddings
+
+**Create Embedding for a Single Record**
+
+To create an embedding for a single record, you can call the `embed!` method on the instance record:
+
+```ruby
+record = Model.find(some_id)
+record.embed!
+```
+
+This will create the embedding and store it in the specified embedding field, along with the timestamp in the `embedded_at` field.
+
+**Create Embeddings for Multiple Records**
+
+To create embeddings for multiple records at once, use the `embed_all!` method:
+
+```ruby
+Model.embed_all!(
+  scope: -> { where(:response.exists => true, :response.ne => nil) },
+  validation: ->(record) { !record.response.blank? }
+)
+```
+
+This method will create embeddings for all records that match the given scope and validation criteria. The method will also print the number of successful and failed embeddings to the console.
+
+**Directly Create Embeddings Using `Spectre.provider_module::Embeddings.create`**
+
+If you need to create an embedding directly without using the model integration, you can use the `Spectre.provider_module::Embeddings.create` method. This can be useful if you want to create embeddings for custom text outside of your models. For example, with OpenAI:
+
+```ruby
+Spectre.provider_module::Embeddings.create("Your text here")
+```
+
+This method sends the text to OpenAI’s API and returns the embedding vector. You can optionally specify a different model by passing it as an argument:
+
+```ruby
+Spectre.provider_module::Embeddings.create("Your text here", model: "text-embedding-ada-002")
+```
+
+### 4. Performing Vector-Based Searches
+
+Once your model is configured as searchable, you can perform vector-based searches on the stored embeddings:
+
+```ruby
+Model.vector_search('Your search query', custom_result_fields: { "response" => 1 }, additional_scopes: [{ "$match" => { "category" => "science" } }])
+```
+
+This method will:
+
+- **Embed the Search Query:** Uses the configured LLM provider to embed the search query.  
+  **Note:** If your text is already embedded, you can pass the embedding (as an array), and it will perform just the search.
+
+- **Perform Vector-Based Search:** Searches the embeddings stored in the specified `search_path`.
+
+- **Return Matching Records:** Provides the matching records with the specified `result_fields` and their `vectorSearchScore`.
+
+**Keyword Arguments:**
+
+- **custom_result_fields:** Limit the fields returned in the search results.
+- **additional_scopes:** Apply additional MongoDB filters to the search results.
+
+### 5. Creating Completions
+
+Spectre provides an interface to create chat completions using your configured LLM provider, allowing you to create dynamic responses, messages, or other forms of text.
+
+**Basic Completion Example**
+
+To create a simple chat completion, use the `Spectre.provider_module::Completions.create` method. You can provide a user prompt and an optional system prompt to guide the response:
+
+```ruby
+Spectre.provider_module::Completions.create(
+  user_prompt: "Tell me a joke.",
+  system_prompt: "You are a funny assistant."
+)
+```
+
+This sends the request to the LLM provider’s API and returns the chat completion.
+
+**Customizing the Completion**
+
+You can customize the behavior by specifying additional parameters such as the model or an `assistant_prompt` to provide further context for the AI’s responses:
+
+```ruby
+Spectre.provider_module::Completions.create(
+  user_prompt: "Tell me a joke.",
+  system_prompt: "You are a funny assistant.",
+  assistant_prompt: "Sure, here's a joke!",
+  model: "gpt-4"
+)
+```
+
+**Using a JSON Schema for Structured Output**
+
+For cases where you need structured output (e.g., for returning specific fields or formatted responses), you can pass a `json_schema` parameter. The schema ensures that the completion conforms to a predefined structure:
+
+```ruby
+json_schema = {
+  name: "completion_response",
+  schema: {
+    type: "object",
+    properties: {
+      response: { type: "string" },
+      final_answer: { type: "string" }
+    },
+    required: ["response", "final_answer"],
+    additionalProperties: false
+  }
+}
+
+Spectre.provider_module::Completions.create(
+  user_prompt: "What is the capital of France?",
+  system_prompt: "You are a knowledgeable assistant.",
+  json_schema: json_schema
+)
+```
+
+This structured format guarantees that the response adheres to the schema you’ve provided, ensuring more predictable and controlled results.
+
+### 6. Creating Dynamic Prompts
+
+Spectre provides a system for creating dynamic prompts based on templates. You can define reusable prompt templates and render them with different parameters in your Rails app (think Ruby on Rails view partials).
+
+**Example Directory Structure for Prompts**
+
+Create a folder structure in your app to hold the prompt templates:
+
+```
+app/spectre/prompts/
+└── rag/
+    ├── system.yml.erb
+    └── user.yml.erb
+```
+
+Each `.yml.erb` file can contain dynamic content and be customized with embedded Ruby (ERB).
+
+**Example Prompt Templates**
+
+- **`system.yml.erb`:**
+
+  ```yaml
+  system: |
+    You are a helpful assistant designed to provide answers based on specific documents and context provided to you.
+    Follow these guidelines:
+    1. Only provide answers based on the context provided.
+    2. Be polite and concise.
+  ```
+
+- **`user.yml.erb`:**
+
+  ```yaml
+  user: |
+    User's query: <%= @query %>
+    Context: <%= @objects.join(", ") %>
+  ```
+
+**Rendering Prompts**
+
+You can render prompts in your Rails application using the `Spectre::Prompt.render` method, which loads and renders the specified prompt template:
+
+```ruby
+# Render a system prompt
+Spectre::Prompt.render(template: 'rag/system')
+
+# Render a user prompt with local variables
+Spectre::Prompt.render(
+  template: 'rag/user',
+  locals: {
+    query: query,
+    objects: objects
+  }
+)
+```
+
+- **`template`:** The path to the prompt template file (e.g., `rag/system`).
+- **`locals`:** A hash of variables to be used inside the ERB template.
+
+**Combining Completions with Prompts**
+
+You can also combine completions and prompts like so:
+
+```ruby
+Spectre.provider_module::Completions.create(
+  user_prompt: Spectre::Prompt.render(template: 'rag/user', locals: { query: @query, user: @user }),
+  system_prompt: Spectre::Prompt.render(template: 'rag/system')
+)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/hiremav/spectre](https://github.com/hiremav/spectre). This project is intended to be a safe, welcoming space for collaboration, and your contributions are greatly appreciated!
+
+1. **Fork** the repository.
+2. **Create** a new feature branch (`git checkout -b my-new-feature`).
+3. **Commit** your changes (`git commit -am 'Add some feature'`).
+4. **Push** the branch (`git push origin my-new-feature`).
+5. **Create** a pull request.
+
+## License
+
+This gem is available as open source under the terms of the MIT License.

data/lib/generators/spectre/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer_file
+        template "spectre_initializer.rb", "config/initializers/spectre.rb"
+      end
+
+      desc "This generator creates system_prompt.yml.erb and user_prompt.yml.erb examples in your app/spectre/prompts folder."
+      def create_prompt_files
+        directory 'rag', 'app/spectre/prompts/rag'
+      end
+    end
+  end
+end

data/lib/generators/spectre/templates/rag/system.yml.erb

@@ -0,0 +1,5 @@
+system: |
+  You are a helpful assistant designed to provide answers based on specific documents and context provided to you.
+  Follow these guidelines:
+  1. Only provide answers based on the context provided to you.
+  2. Never mention the context directly in your responses.

data/lib/generators/spectre/templates/rag/user.yml.erb

@@ -0,0 +1,3 @@
+user: |
+  User's query: <%= @query %>
+  Context: <%= @objects.join(", ") %>

data/lib/generators/spectre/templates/spectre_initializer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Spectre.setup do |config|
+  # Chose your LLM (openai, cohere, ollama)
+  config.llm_provider = :openai
+  # Set the API key for your chosen LLM
+  config.api_key = ENV.fetch('CHATGPT_API_TOKEN')
+end

data/lib/spectre/embeddable.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative 'logging'
+require_relative 'openai'
+
+module Spectre
+  module Embeddable
+    include Spectre::Logging
+
+    class NoEmbeddableFieldsError < StandardError; end
+    class EmbeddingValidationError < StandardError; end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Converts the specified fields into a JSON representation suitable for embedding.
+    #
+    # @return [String] A JSON string representing the vectorized content of the specified fields.
+    #
+    # @raise [NoEmbeddableFieldsError] if no embeddable fields are defined in the model.
+    #
+    def as_vector
+      raise NoEmbeddableFieldsError, "Embeddable fields are not defined" if self.class.embeddable_fields.empty?
+
+      vector_data = self.class.embeddable_fields.map { |field| [field, send(field)] }.to_h
+      vector_data.to_json
+    end
+
+    # Embeds the vectorized content and saves it to the specified fields.
+    #
+    # @param validation [Proc, nil] A validation block that returns true if the embedding should proceed.
+    # @param embedding_field [Symbol] The field in which to store the generated embedding (default: :embedding).
+    # @param timestamp_field [Symbol] The field in which to store the embedding timestamp (default: :embedded_at).
+    #
+    # @example
+    #   embed!(validation: ->(record) { !record.response.nil? }, embedding_field: :custom_embedding, timestamp_field: :custom_embedded_at)
+    #
+    # @raise [EmbeddingValidationError] if the validation block fails.
+    #
+    def embed!(validation: nil, embedding_field: :embedding, timestamp_field: :embedded_at)
+      if validation && !validation.call(self)
+        raise EmbeddingValidationError, "Validation failed for embedding"
+      end
+
+      embedding_value = Spectre.provider_module::Embeddings.create(as_vector)
+      send("#{embedding_field}=", embedding_value)
+      send("#{timestamp_field}=", Time.now)
+      save!
+    end
+
+    module ClassMethods
+      include Spectre::Logging
+
+      def embeddable_field(*fields)
+        @embeddable_fields = fields
+      end
+
+      def embeddable_fields
+        @embeddable_fields ||= []
+      end
+
+      # Embeds the vectorized content for all records that match the optional scope
+      # and pass the validation check. Saves the embedding and timestamp to the specified fields.
+      # Also counts the number of successful and failed embeddings.
+      #
+      # @param scope [Proc, nil] A scope or query to filter records (default: all records).
+      # @param validation [Proc, nil] A validation block that returns true if the embedding should proceed for a record.
+      # @param embedding_field [Symbol] The field in which to store the generated embedding (default: :embedding).
+      # @param timestamp_field [Symbol] The field in which to store the embedding timestamp (default: :embedded_at).
+      #
+      # @example
+      #   embed_all!(
+      #     scope: -> { where(:response.exists => true, :response.ne => nil) },
+      #     validation: ->(record) { !record.response.nil? },
+      #     embedding_field: :custom_embedding,
+      #     timestamp_field: :custom_embedded_at
+      #   )
+      #
+      def embed_all!(scope: nil, validation: nil, embedding_field: :embedding, timestamp_field: :embedded_at)
+        records = scope ? instance_exec(&scope) : all
+
+        success_count = 0
+        failure_count = 0
+
+        records.each do |record|
+          begin
+            record.embed!(
+              validation: validation,
+              embedding_field: embedding_field,
+              timestamp_field: timestamp_field
+            )
+            success_count += 1
+          rescue EmbeddingValidationError => e
+            log_error("Failed to embed record #{record.id}: #{e.message}")
+            failure_count += 1
+          rescue => e
+            log_error("Unexpected error embedding record #{record.id}: #{e.message}")
+            failure_count += 1
+          end
+        end
+
+        puts "Successfully embedded #{success_count} records."
+        puts "Failed to embed #{failure_count} records."
+      end
+    end
+  end
+end

data/lib/spectre/logging.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'time'
+
+module Spectre
+  module Logging
+    def logger
+      @logger ||= create_logger
+    end
+
+    def log_error(message)
+      logger.error(message)
+    end
+
+    def log_info(message)
+      logger.info(message)
+    end
+
+    def log_debug(message)
+      logger.debug(message)
+    end
+
+    private
+
+    def create_logger
+      Logger.new(STDOUT).tap do |log|
+        log.progname = 'Spectre'
+        log.level = Logger::DEBUG # Set the default log level (can be changed to INFO, WARN, etc.)
+        log.formatter = proc do |severity, datetime, progname, msg|
+          "#{datetime.utc.iso8601} #{severity} #{progname}: #{msg}\n"
+        end
+      end
+    end
+  end
+end

data/lib/spectre/openai/completions.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Openai
+    class Completions
+      API_URL = 'https://api.openai.com/v1/chat/completions'
+      DEFAULT_MODEL = 'gpt-4o-mini'
+
+      # Class method to generate a completion based on a user prompt
+      #
+      # @param user_prompt [String] the user's input to generate a completion for
+      # @param system_prompt [String] an optional system prompt to guide the AI's behavior
+      # @param assistant_prompt [String] an optional assistant prompt to provide context for the assistant's behavior
+      # @param model [String] the model to be used for generating completions, defaults to DEFAULT_MODEL
+      # @param json_schema [Hash, nil] an optional JSON schema to enforce structured output
+      # @param max_tokens [Integer] the maximum number of tokens for the completion (default: 50)
+      # @return [String] the generated completion text
+      # @raise [APIKeyNotConfiguredError] if the API key is not set
+      # @raise [RuntimeError] for general API errors or unexpected issues
+      def self.create(user_prompt:, system_prompt: "You are a helpful assistant.", assistant_prompt: nil, model: DEFAULT_MODEL, json_schema: nil, max_tokens: nil)
+        api_key = Spectre.api_key
+        raise APIKeyNotConfiguredError, "API key is not configured" unless api_key
+
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 10 # seconds
+        http.open_timeout = 10 # seconds
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        })
+
+        request.body = generate_body(user_prompt, system_prompt, assistant_prompt, model, json_schema, max_tokens).to_json
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "OpenAI API Error: #{response.code} - #{response.message}: #{response.body}"
+        end
+
+        parsed_response = JSON.parse(response.body)
+
+        # Check if the response contains a refusal
+        if parsed_response.dig('choices', 0, 'message', 'refusal')
+          raise "Refusal: #{parsed_response.dig('choices', 0, 'message', 'refusal')}"
+        end
+
+        # Check if the finish reason is "length", indicating incomplete response
+        if parsed_response.dig('choices', 0, 'finish_reason') == "length"
+          raise "Incomplete response: The completion was cut off due to token limit."
+        end
+
+        # Return the structured output if it's included
+        parsed_response.dig('choices', 0, 'message', 'content')
+      rescue JSON::ParserError => e
+        raise "JSON Parse Error: #{e.message}"
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise "Request Timeout: #{e.message}"
+      end
+
+      private
+
+      # Helper method to generate the request body
+      #
+      # @param user_prompt [String] the user's input to generate a completion for
+      # @param system_prompt [String] an optional system prompt to guide the AI's behavior
+      # @param assistant_prompt [String] an optional assistant prompt to provide context for the assistant's behavior
+      # @param model [String] the model to be used for generating completions
+      # @param json_schema [Hash, nil] an optional JSON schema to enforce structured output
+      # @param max_tokens [Integer, nil] the maximum number of tokens for the completion
+      # @return [Hash] the body for the API request
+      def self.generate_body(user_prompt, system_prompt, assistant_prompt, model, json_schema, max_tokens)
+        messages = [
+          { role: 'system', content: system_prompt },
+          { role: 'user', content: user_prompt }
+        ]
+
+        # Add the assistant prompt if provided
+        messages << { role: 'assistant', content: assistant_prompt } if assistant_prompt
+
+        body = {
+          model: model,
+          messages: messages,
+        }
+        body['max_tokens'] = max_tokens if max_tokens
+
+        # Add the JSON schema as part of response_format if provided
+        if json_schema
+          body[:response_format] = {
+            type: 'json_schema',
+            json_schema: json_schema
+          }
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/spectre/openai/embeddings.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Openai
+    class Embeddings
+      API_URL = 'https://api.openai.com/v1/embeddings'
+      DEFAULT_MODEL = 'text-embedding-3-small'
+
+      # Class method to generate embeddings for a given text
+      #
+      # @param text [String] the text input for which embeddings are to be generated
+      # @param model [String] the model to be used for generating embeddings, defaults to DEFAULT_MODEL
+      # @return [Array<Float>] the generated embedding vector
+      # @raise [APIKeyNotConfiguredError] if the API key is not set
+      # @raise [RuntimeError] for general API errors or unexpected issues
+      def self.create(text, model: DEFAULT_MODEL)
+        api_key = Spectre.api_key
+        raise APIKeyNotConfiguredError, "API key is not configured" unless api_key
+
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 10 # seconds
+        http.open_timeout = 10 # seconds
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        })
+
+        request.body = { model: model, input: text }.to_json
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "OpenAI API Error: #{response.code} - #{response.message}: #{response.body}"
+        end
+
+        JSON.parse(response.body).dig('data', 0, 'embedding')
+      rescue JSON::ParserError => e
+        raise "JSON Parse Error: #{e.message}"
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise "Request Timeout: #{e.message}"
+      end
+    end
+  end
+end

data/lib/spectre/openai.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Openai
+    # Require each specific client file here
+    require_relative 'openai/embeddings'
+    require_relative 'openai/completions'
+  end
+end

data/lib/spectre/prompt.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'yaml'
+
+module Spectre
+  class Prompt
+    PROMPTS_PATH = File.join(Dir.pwd, 'app', 'spectre', 'prompts')
+
+    # Render a prompt by reading and rendering the YAML template
+    #
+    # @param template [String] The path to the template file, formatted as 'type/prompt' (e.g., 'rag/system')
+    # @param locals [Hash] Variables to be passed to the template for rendering
+    #
+    # @return [String] Rendered prompt
+    def self.render(template:, locals: {})
+      type, prompt = split_template(template)
+      file_path = prompt_file_path(type, prompt)
+
+      raise "Prompt file not found: #{file_path}" unless File.exist?(file_path)
+
+      template_content = File.read(file_path)
+      erb_template = ERB.new(template_content)
+
+      context = Context.new(locals)
+      rendered_prompt = erb_template.result(context.get_binding)
+
+      YAML.safe_load(rendered_prompt)[prompt]
+    end
+
+    private
+
+    # Split the template parameter into type and prompt
+    #
+    # @param template [String] Template path in the format 'type/prompt' (e.g., 'rag/system')
+    # @return [Array<String, String>] An array containing the type and prompt
+    def self.split_template(template)
+      template.split('/')
+    end
+
+    # Build the path to the desired prompt file
+    #
+    # @param type [String] Name of the prompt folder
+    # @param prompt [String] Type of prompt (e.g., 'system', 'user')
+    #
+    # @return [String] Full path to the template file
+    def self.prompt_file_path(type, prompt)
+      "#{PROMPTS_PATH}/#{type}/#{prompt}.yml.erb"
+    end
+
+    # Helper class to handle the binding for ERB rendering
+    class Context
+      def initialize(locals)
+        locals.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+      end
+
+      # Returns binding for ERB template rendering
+      def get_binding
+        binding
+      end
+    end
+  end
+end

data/lib/spectre/searchable.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Searchable
+    def self.included(base)
+      unless base.ancestors.map(&:to_s).include?('Mongoid::Document')
+        raise "Spectre::Searchable can only be included in Mongoid models. The class #{base.name} does not appear to be a Mongoid model."
+      end
+
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Configure the path to the embedding field for the vector search.
+      #
+      # @param path [String] The path to the embedding field.
+      def configure_spectre_search_path(path)
+        @search_path = path
+      end
+
+      # Configure the index to be used for the vector search.
+      #
+      # @param index [String] The name of the vector index.
+      def configure_spectre_search_index(index)
+        @search_index = index
+      end
+
+      # Configure the default fields to include in the search results.
+      #
+      # @param fields [Hash] The fields to include in the results, with their MongoDB projection configuration.
+      def configure_spectre_result_fields(fields)
+        @result_fields = fields
+      end
+
+      # Provide access to the configured search path.
+      #
+      # @return [String] The configured search path.
+      def search_path
+        @search_path || 'embedding'  # Default to 'embedding' if not configured
+      end
+
+      # Provide access to the configured search index.
+      #
+      # @return [String] The configured search index.
+      def search_index
+        @search_index || 'vector_index'  # Default to 'vector_index' if not configured
+      end
+
+      # Provide access to the configured result fields.
+      #
+      # @return [Hash, nil] The configured result fields, or nil if not configured.
+      def result_fields
+        @result_fields
+      end
+
+      # Searches based on a query string by first embedding the query.
+      #
+      # @param query [String] The text query to embed and search for.
+      # @param limit [Integer] The maximum number of results to return (default: 5).
+      # @param additional_scopes [Array<Hash>] Additional MongoDB aggregation stages to filter or modify results.
+      # @param custom_result_fields [Hash, nil] Custom fields to include in the search results, overriding the default.
+      #
+      # @return [Array<Hash>] The search results, including the configured fields and score.
+      #
+      # @example Basic search with configured result fields
+      #   results = Model.vector_search("What is AI?")
+      #
+      # @example Search with custom result fields
+      #   results = Model.vector_search(
+      #     "What is AI?",
+      #     limit: 10,
+      #     custom_result_fields: { "some_additional_field": 1, "another_field": 1 }
+      #   )
+      #
+      # @example Search with additional filtering using scopes
+      #   results = Model.vector_search(
+      #     "What is AI?",
+      #     limit: 10,
+      #     additional_scopes: [{ "$match": { "some_field": "some_value" } }]
+      #   )
+      #
+      # @example Combining custom result fields and additional scopes
+      #   results = Model.vector_search(
+      #     "What is AI?",
+      #     limit: 10,
+      #     additional_scopes: [{ "$match": { "some_field": "some_value" } }],
+      #     custom_result_fields: { "some_additional_field": 1, "another_field": 1 }
+      #   )
+      #
+      def vector_search(query, limit: 5, additional_scopes: [], custom_result_fields: nil)
+        # Check if the query is a string (needs embedding) or an array (already embedded)
+        embedded_query = if query.is_a?(String)
+                           Spectre.provider_module::Embeddings.create(query)
+                         elsif query.is_a?(Array) && query.all? { |e| e.is_a?(Float) }
+                           query
+                         else
+                           raise ArgumentError, "Query must be a String or an Array of Floats"
+                         end
+
+        # Build the MongoDB aggregation pipeline
+        pipeline = [
+          {
+            "$vectorSearch": {
+              "queryVector": embedded_query,
+              "path": search_path,
+              "numCandidates": 100,
+              "limit": limit,
+              "index": search_index
+            }
+          }
+        ]
+
+        # Add any additional scopes provided
+        pipeline.concat(additional_scopes) if additional_scopes.any?
+
+        # Determine the fields to include in the results
+        fields_to_project = custom_result_fields || result_fields || {}
+        fields_to_project["score"] = { "$meta": "vectorSearchScore" }
+
+        # Add the project stage with the fields to project
+        pipeline << { "$project": fields_to_project }
+
+        self.collection.aggregate(pipeline).to_a
+      end
+    end
+  end
+end

data/lib/spectre/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Spectre # :nodoc:all
+  VERSION = "1.0.0"
+end

data/lib/spectre.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "spectre/version"
+require "spectre/embeddable"
+require 'spectre/searchable'
+require "spectre/openai"
+require "spectre/logging"
+require 'spectre/prompt'
+
+module Spectre
+  class APIKeyNotConfiguredError < StandardError; end
+
+  VALID_LLM_PROVIDERS = {
+    openai: Spectre::Openai,
+    # cohere: Spectre::Cohere,
+    # ollama: Spectre::Ollama
+  }.freeze
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def spectre(*modules)
+      modules.each do |mod|
+        case mod
+        when :embeddable
+          include Spectre::Embeddable
+        when :searchable
+          include Spectre::Searchable
+        else
+          raise ArgumentError, "Unknown spectre module: #{mod}"
+        end
+      end
+    end
+  end
+
+  class << self
+    attr_accessor :api_key, :llm_provider
+
+    def setup
+      yield self
+      validate_llm_provider!
+    end
+
+    def provider_module
+      VALID_LLM_PROVIDERS[llm_provider] || raise("LLM provider #{llm_provider} not supported")
+    end
+
+    private
+
+    def validate_llm_provider!
+      unless VALID_LLM_PROVIDERS.keys.include?(llm_provider)
+        raise ArgumentError, "Invalid llm_provider: #{llm_provider}. Must be one of: #{VALID_LLM_PROVIDERS.keys.join(', ')}"
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: spectre_ai
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ilya Klapatok
+- Matthew Black
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  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'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: Spectre is a Ruby gem that makes it easy to AI-enable your Ruby on Rails
+  application.
+email: ilya@hiremav.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/generators/spectre/install_generator.rb
+- lib/generators/spectre/templates/rag/system.yml.erb
+- lib/generators/spectre/templates/rag/user.yml.erb
+- lib/generators/spectre/templates/spectre_initializer.rb
+- lib/spectre.rb
+- lib/spectre/embeddable.rb
+- lib/spectre/logging.rb
+- lib/spectre/openai.rb
+- lib/spectre/openai/completions.rb
+- lib/spectre/openai/embeddings.rb
+- lib/spectre/prompt.rb
+- lib/spectre/searchable.rb
+- lib/spectre/version.rb
+homepage: https://github.com/hiremav/spectre
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: Spectre
+test_files: []