ask-rag 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a55e3f456d3e444c8aa58ba2b4c0f909de86bffe87e3e08a0a50becdddd2232e
-  data.tar.gz: fd944ef839c03e0a5bf2b597e4867f05c835d62e6a3433529d8e5bfb4bc9ad54
+  metadata.gz: b79936f65b8b4b8f7cbfc1667703b645df6f411e84e7ee543071e4fabe9e6015
+  data.tar.gz: 474bac5cbc7f1d3f26b3ec0115591947577a3957aff4733a815f3f96b6f63dd6
 SHA512:
-  metadata.gz: 698e26ae24b01752d2032ec7345b3671902e1ead593685902b308ebf81b3fdde203581184686e8a95deb02a981a42e46cf99cfb9be7b2a6bd3977f182228bd90
-  data.tar.gz: 722a7d7ac59603a15932adf20e4a99452f7f031e6f0623f63645701e36c1350730bc331e024666da953f185ac101bec115913fa53cc343f141e6a4eb0d220aba
+  metadata.gz: 3b7042d0c1f27aee6ceb4a21122f3c84691afb3b635a8b2f25f94a8c8cac3d633e09507f5a5b11347c241885016bdca1261be9322a0823034c4d97e11d8bce9e
+  data.tar.gz: 48b984042f7138262c13cd1458fa9191ed914909b35690b524cf3917e8837009644d71078908c47e1d1332b8895c4cee3ec5e453315442ef13091ff77420c6da

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [0.2.1] — 2026-07-26
+
+### Fixed
+
+- **PGVector model tracking** — same fix as InMemory: now tracks the embedding model used during `add` and reuses it for query embedding. Also raises `EmbeddingError` instead of silently returning a zero vector on failure.
+
+- **PGVector document mutability** — no longer calls `define_singleton_method(:score)` on frozen `Ask::Document`. Score is now returned in `metadata[:score]` consistently with InMemory.
+
+- **PGVector embed_query** — now accepts the query text as an argument (was hardcoded to embed the literal string "query").
+
+### Added
+
+- **`similarity_search_by_vector`** — search using a raw vector instead of text. Available on both InMemory and PGVector stores. Accepts `limit:` and `filter:` params.
+
+  ```ruby
+  store.similarity_search_by_vector([0.1, 0.2, ...], limit: 5)
+  ```
+
+- **`Ask::RAG::Loader::JSON`** — loads JSON files. Supports arrays of objects (one document per object) and single objects. Configurable `content_key` and `metadata_keys`.
+
+  ```ruby
+  loader = Ask::RAG::Loader::JSON.new(content_key: "body")
+  docs = loader.load("articles.json")
+  ```
+
+- **Directory loader** now also recognizes `.json` files.
+
+### Tested
+
+- 65 tests, 163 assertions, 0 failures
+
 ## [0.2.0] — 2026-07-26
 
 ### Fixed

data/lib/ask/rag/loader/directory.rb

@@ -26,6 +26,7 @@ module Ask
           ".html" => :html,
           ".htm" => :html,
           ".csv" => :csv,
+          ".json" => :json,
           ".pdf" => :pdf
         }.freeze
 
@@ -96,6 +97,7 @@ module Ask
           when :markdown then Loader::Markdown.new
           when :html then defined?(Loader::HTML) ? Loader::HTML.new : nil
           when :csv then Loader::CSV.new
+          when :json then Loader::JSON.new
           when :pdf then defined?(Loader::PDF) ? Loader::PDF.new : nil
           end
         end

data/lib/ask/rag/loader/json.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Ask
+  module RAG
+    module Loader
+      # Loads a JSON file as documents.
+      #
+      # Supports two modes:
+      # 1. Array of objects — each object becomes one document.
+      #    Specify +content_key+ and +metadata_keys+ to map fields.
+      # 2. Single object — becomes one document.
+      #    Specify +content_key+ for which field holds the text.
+      #
+      # @example Array of objects
+      #   # [{ "title": "...", "body": "...", "tags": [...] }, ...]
+      #   loader = Ask::RAG::Loader::JSON.new(content_key: "body")
+      #   docs = loader.load("articles.json")
+      #
+      # @example With metadata mapping
+      #   loader = Ask::RAG::Loader::JSON.new(
+      #     content_key: "content",
+      #     metadata_keys: ["source", "date"]
+      #   )
+      #
+      class JSON < Base
+        # @param content_key [String] key whose value becomes document content
+        # @param metadata_keys [Array<String>, nil] keys to include in metadata
+        #   (nil = all keys except content_key)
+        def initialize(content_key: "content", metadata_keys: nil)
+          @content_key = content_key
+          @metadata_keys = metadata_keys
+        end
+
+        def load(path)
+          raw = ::JSON.parse(File.read(path))
+          items = raw.is_a?(Array) ? raw : [raw]
+
+          items.map { |item| build_document(item, path) }
+        end
+
+        private
+
+        def build_document(item, path)
+          content = item[@content_key].to_s
+          metadata = { source: path }
+
+          if @metadata_keys
+            @metadata_keys.each do |key|
+              metadata[key] = item[key] if item.key?(key)
+            end
+          else
+            item.each do |key, value|
+              next if key == @content_key
+              metadata[key] = value if value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+            end
+          end
+
+          Ask::Document.new(content: content, metadata: metadata)
+        end
+      end
+    end
+  end
+end

data/lib/ask/rag/vector_store/base.rb

@@ -41,6 +41,17 @@ module Ask
         raise NotImplementedError
       end
 
+      # Search by a raw vector instead of a text query.
+      # Useful when you've already embedded the query externally.
+      #
+      # @param vector [Array<Float>] the query vector
+      # @param limit [Integer] maximum number of results
+      # @param filter [Hash, nil] metadata filter
+      # @return [Array<Ask::Document>] documents with +:score+ in metadata
+      def similarity_search_by_vector(vector, limit: 10, filter: nil)
+        raise NotImplementedError
+      end
+
       # Remove documents by ID.
       # @param ids [Array<String>] document IDs to remove
       def delete(ids)

data/lib/ask/rag/vector_store/in_memory.rb

@@ -81,12 +81,22 @@ module Ask
         # @return [Array<Ask::Document>] documents with +:score+ and +:mmr_score+ in metadata
         def similarity_search(query, limit: 10, filter: nil, mmr: false, diversity_bonus: 0.3)
           query_vector = embed_query
+          search_by_vector(query_vector, limit: limit, filter: filter,
+                           mmr: mmr, diversity_bonus: diversity_bonus)
+        end
+
+        def similarity_search_by_vector(vector, limit: 10, filter: nil)
+          search_by_vector(vector, limit: limit, filter: filter)
+        end
 
+        private
+
+        def search_by_vector(vector, limit:, filter: nil, mmr: false, diversity_bonus: 0.3)
           candidates = @mutex.synchronize do
             @entries.filter_map do |_id, entry|
               next if filter && !matches_filter?(entry.document.metadata, filter)
 
-              score = cosine_similarity(query_vector, entry.vector)
+              score = cosine_similarity(vector, entry.vector)
               [entry, score]
             end
           end
@@ -94,7 +104,7 @@ module Ask
           candidates.sort_by! { |_, score| -score }
 
           if mmr
-            apply_mmr(candidates, query_vector, limit, diversity_bonus)
+            apply_mmr(candidates, vector, limit, diversity_bonus)
           else
             candidates.first(limit).map do |entry, score|
               build_result(entry, score: score)
@@ -102,6 +112,8 @@ module Ask
           end
         end
 
+        public
+
         def delete(ids)
           @mutex.synchronize do
             ids.each { |id| @entries.delete(id) }

data/lib/ask/rag/vector_store/pgvector.rb

@@ -19,7 +19,7 @@ module Ask
       #
       # @example Usage
       #   store = Ask::RAG::VectorStore::PGVector.new(
-      #     table_name: :documents,
+      #     table_name: :embeddings,
       #     embedding_column: :embedding
       #   )
       #   store.add(chunks, model: "text-embedding-3-small")
@@ -38,18 +38,19 @@ module Ask
           @metadata_column = metadata_column.to_s
           @embedding_column = embedding_column.to_s
           @model_class = model_class || infer_model_class
+          @embedding_model = nil
         end
 
         def add(documents, model:, batch_size: 20)
           ids = []
-          model_class = @model_class
+          @embedding_model = model
 
           documents.each_slice(batch_size) do |batch|
             texts = batch.map(&:content)
             vectors = embed_texts(texts, model)
 
             batch.each_with_index do |doc, idx|
-              record = model_class.create!(
+              record = @model_class.create!(
                 @content_column => doc.content,
                 @metadata_column => doc.metadata,
                 @embedding_column => vectors[idx]
@@ -63,11 +64,16 @@ module Ask
 
         def similarity_search(query, limit: 10, filter: nil, mmr: false, diversity_bonus: 0.3)
           query_vector = embed_query(query)
+          similarity_search_by_vector(query_vector, limit: limit, filter: filter)
+        end
+
+        def similarity_search_by_vector(vector, limit: 10, filter: nil)
+          vector_str = vector.is_a?(Array) ? "[#{vector.join(',')}]" : vector.to_s
           column = "#{@table_name}.#{@embedding_column}"
           model_class = @model_class
 
           scope = model_class
-            .select("#{@table_name}.*, 1 - (#{column} <=> '#{query_vector.to_s}') AS score")
+            .select("#{@table_name}.*, 1 - (#{column} <=> '#{vector_str}') AS score")
             .where("#{column} IS NOT NULL")
 
           if filter
@@ -77,16 +83,18 @@ module Ask
           end
 
           records = scope
-            .order(Arel.sql("#{column} <=> '#{query_vector.to_s}'"))
+            .order(Arel.sql("#{column} <=> '#{vector_str}'"))
             .limit(limit)
 
           records.map do |record|
-            doc = Ask::Document.new(
+            Ask::Document.new(
               content: record.send(@content_column),
-              metadata: (record.send(@metadata_column) || {}).merge(db_id: record.id)
+              metadata: (record.send(@metadata_column) || {}).merge(
+                score: record.score,
+                db_id: record.id
+              ),
+              id: record.id.to_s
             )
-            doc.define_singleton_method(:score) { record.score }
-            doc
           end
         end
 
@@ -117,13 +125,14 @@ module Ask
           Array(raw).map { |v| Array(v).map(&:to_f) }
         end
 
-        def embed_query(query)
-          provider = resolve_provider("text-embedding-3-small")
-          raw = provider.embed(query, model: "text-embedding-3-small")
+        def embed_query(query = "query")
+          model = @embedding_model || "text-embedding-3-small"
+          provider = resolve_provider(model)
+          raw = provider.embed(query, model: model)
           raw = raw.output if raw.is_a?(Ask::Result)
           Array(raw).flatten.map(&:to_f)
-        rescue StandardError
-          [0.0] * 1536
+        rescue StandardError => e
+          raise EmbeddingError, "Failed to embed query with model #{model}: #{e.message}"
         end
 
         def resolve_provider(model)

data/lib/ask/rag/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module RAG
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/ask/rag.rb

@@ -14,6 +14,7 @@ require_relative "rag/loader/base"
 require_relative "rag/loader/text"
 require_relative "rag/loader/markdown"
 require_relative "rag/loader/csv"
+require_relative "rag/loader/json"
 require_relative "rag/loader/directory"
 
 # Optional loaders (loaded only when their dependency gem is available)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rag
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -111,6 +111,7 @@ files:
 - lib/ask/rag/loader/csv.rb
 - lib/ask/rag/loader/directory.rb
 - lib/ask/rag/loader/html.rb
+- lib/ask/rag/loader/json.rb
 - lib/ask/rag/loader/markdown.rb
 - lib/ask/rag/loader/pdf.rb
 - lib/ask/rag/loader/text.rb