semantic-cache 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a16f649e20d3989d12d16c4e52b809c7f91fc81383d83cdd9e4b86306ceb8d4
-  data.tar.gz: 8e1a0cf3bfdec291aa24141ffdd4c32f31f4d33802e10b4bc08e36b5576daec1
+  metadata.gz: fe7443a701b34378500d134735a7d00eea7ab078cfaf036d7b11406495eed1b9
+  data.tar.gz: 4f079d89a8e0f977ac89af9ba09841e9064c7121b649ea91f9fb430475f0a628
 SHA512:
-  metadata.gz: 339b424cff6654e37aa888b22ef9a9ab8f06d69fcda0d3ed42f62ded02d852d29ac18a3a1ee570539231e8cbdd83922ef909cdc24eb11e301859f73906ca774c
-  data.tar.gz: 857a0e0013fb7d93c006c87418c9adad1fbd0cfb79faa92cadcbf8a35ed9c690e3c26f02df2247d62e6a48254959e29bffc8457a6bef55e3c6807f624d54502c
+  metadata.gz: 8b79b8b26a38343eed5db1e008be0ca4417277c33fb3ab0beda3dc8b6440d79a3d8d5e39301714ba12cf1a268be3dbe3307f639c8bc0dea83dd34e9186d4c566
+  data.tar.gz: bd19ca0b045887bffa9c2510977d6e005ea1fad50a4e44012e1e88a6a051100286fe09a847848ffa0ddd78b20212510b51ed3175fc4ed5d9a77edf2ea45a0929

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2025-01-29
+
+### Added
+
+- **Input validation** — `cache.fetch(nil)` and `cache.fetch("")` now raise `ArgumentError` early instead of failing at the API level
+- **API timeout** — embedding generation is wrapped in `Timeout.timeout` (default: 30s, configurable via `config.embedding_timeout`)
+- **Max cache size** — both Memory and Redis stores support `max_size` with LRU eviction (oldest entry by `created_at` is evicted when full)
+- **Redis store tests** — full test coverage for write, entries, delete, tags, clear, size, max_size, and namespace
+- **Rails integration tests** — tests for `with_cache`, `current`, `Cacheable` concern, and exception safety
+- **Embedding batch validation** — `generate_batch` validates each element in the array
+
+### Improved
+
+- Test coverage increased from 85.6% to 97.67% (113 tests, 0 failures)
+- Configuration now includes `embedding_timeout` and `max_cache_size` attributes
+
 ## [0.1.0] - 2025-01-29
 
 ### Added

data/lib/semantic_cache/cache.rb

@@ -13,7 +13,8 @@ module SemanticCache
       store_options: {},
       default_ttl: nil,
       namespace: nil,
-      track_costs: nil
+      track_costs: nil,
+      max_size: nil
     )
       config = SemanticCache.configuration
 
@@ -21,6 +22,7 @@ module SemanticCache
       @default_ttl = default_ttl || config.default_ttl
       @track_costs = track_costs.nil? ? config.track_costs : track_costs
       @namespace = namespace || config.namespace
+      @max_size = max_size || config.max_cache_size
 
       @embedding = Embedding.new(
         model: embedding_model || config.embedding_model,
@@ -43,6 +45,7 @@ module SemanticCache
     #   model: - Model name for cost tracking
     def fetch(query, ttl: nil, tags: [], model: nil, metadata: {}, &block)
       raise ArgumentError, "A block is required" unless block_given?
+      validate_query!(query)
 
       start_time = Time.now
 
@@ -133,6 +136,13 @@ module SemanticCache
 
     private
 
+    def validate_query!(query)
+      raise ArgumentError, "query cannot be nil" if query.nil?
+
+      query_str = query.to_s.strip
+      raise ArgumentError, "query cannot be blank" if query_str.empty?
+    end
+
     def find_similar(query_embedding)
       entries = @store.entries
       return nil if entries.empty?
@@ -168,11 +178,13 @@ module SemanticCache
     end
 
     def build_store(type, options)
+      store_max_size = @max_size
+
       case type
       when :memory, "memory"
-        Stores::Memory.new(**options)
+        Stores::Memory.new(max_size: store_max_size, **options)
       when :redis, "redis"
-        Stores::Redis.new(**options)
+        Stores::Redis.new(max_size: store_max_size, **options)
       when Stores::Memory, Stores::Redis
         type # Already instantiated
       else

data/lib/semantic_cache/configuration.rb

@@ -10,7 +10,9 @@ module SemanticCache
                   :store_options,
                   :track_costs,
                   :model_costs,
-                  :namespace
+                  :namespace,
+                  :embedding_timeout,
+                  :max_cache_size
 
     # Cost per 1K tokens (USD)
     DEFAULT_MODEL_COSTS = {
@@ -41,6 +43,8 @@ module SemanticCache
       @track_costs = true
       @model_costs = DEFAULT_MODEL_COSTS.dup
       @namespace = "semantic_cache"
+      @embedding_timeout = 30       # seconds
+      @max_cache_size = nil         # nil = unlimited
     end
 
     def cost_for(model)

data/lib/semantic_cache/embedding.rb

@@ -1,24 +1,33 @@
 # frozen_string_literal: true
 
 require "openai"
+require "timeout"
 
 module SemanticCache
   class Embedding
     def initialize(model: nil, api_key: nil)
       config = SemanticCache.configuration
       @model = model || config.embedding_model
+      @timeout = config.embedding_timeout
       @client = OpenAI::Client.new(access_token: api_key || config.openai_api_key)
     end
 
     # Generate an embedding vector for the given text.
     # Returns an Array of Floats.
+    #
+    # Raises ArgumentError if text is nil or empty.
+    # Raises SemanticCache::Error on API failure or timeout.
     def generate(text)
-      response = @client.embeddings(
-        parameters: {
-          model: @model,
-          input: text
-        }
-      )
+      validate_input!(text)
+
+      response = with_timeout do
+        @client.embeddings(
+          parameters: {
+            model: @model,
+            input: text
+          }
+        )
+      end
 
       data = response.dig("data", 0, "embedding")
       raise Error, "Failed to generate embedding: #{response}" if data.nil?
@@ -28,18 +37,46 @@ module SemanticCache
 
     # Generate embeddings for multiple texts in a single API call.
     # Returns an Array of Arrays of Floats.
+    #
+    # Raises ArgumentError if texts is empty or contains nil/blank entries.
+    # Raises SemanticCache::Error on API failure or timeout.
     def generate_batch(texts)
-      response = @client.embeddings(
-        parameters: {
-          model: @model,
-          input: texts
-        }
-      )
+      raise ArgumentError, "texts must be a non-empty Array" if !texts.is_a?(Array) || texts.empty?
+
+      texts.each_with_index do |t, i|
+        validate_input!(t, label: "texts[#{i}]")
+      end
+
+      response = with_timeout do
+        @client.embeddings(
+          parameters: {
+            model: @model,
+            input: texts
+          }
+        )
+      end
 
       data = response["data"]
       raise Error, "Failed to generate embeddings: #{response}" if data.nil?
 
       data.sort_by { |d| d["index"] }.map { |d| d["embedding"] }
     end
+
+    private
+
+    def validate_input!(text, label: "query")
+      raise ArgumentError, "#{label} cannot be nil" if text.nil?
+
+      text_str = text.to_s.strip
+      raise ArgumentError, "#{label} cannot be blank" if text_str.empty?
+    end
+
+    def with_timeout(&block)
+      if @timeout && @timeout > 0
+        Timeout.timeout(@timeout, Error, "Embedding API request timed out after #{@timeout}s", &block)
+      else
+        block.call
+      end
+    end
   end
 end

data/lib/semantic_cache/stores/memory.rb

@@ -6,18 +6,24 @@ module SemanticCache
   module Stores
     # Thread-safe in-memory cache store.
     # Good for development, testing, and single-process apps.
+    #
+    # Options:
+    #   max_size: Maximum number of entries to keep. When exceeded, the oldest
+    #             entry (by created_at) is evicted. nil = unlimited.
     class Memory
       include MonitorMixin
 
-      def initialize(**_options)
+      def initialize(max_size: nil, **_options)
         super()
         @data = {}
         @tags_index = Hash.new { |h, k| h[k] = Set.new }
+        @max_size = max_size
       end
 
-      # Store a cache entry.
+      # Store a cache entry. Evicts the oldest entry if max_size is reached.
       def write(key, entry)
         synchronize do
+          evict_oldest! if @max_size && @data.size >= @max_size && !@data.key?(key)
           @data[key] = entry
           entry.tags.each { |tag| @tags_index[tag].add(key) }
         end
@@ -73,6 +79,12 @@ module SemanticCache
         expired_keys = @data.select { |_k, v| v.expired? }.keys
         expired_keys.each { |key| delete(key) }
       end
+
+      # Evict the oldest entry (by created_at) to make room for a new one.
+      def evict_oldest!
+        oldest_key = @data.min_by { |_k, v| v.created_at }&.first
+        delete(oldest_key) if oldest_key
+      end
     end
   end
 end

data/lib/semantic_cache/stores/redis.rb

@@ -8,14 +8,21 @@ module SemanticCache
     # Suitable for production, multi-process, and distributed apps.
     #
     # Requires the `redis` gem: gem install redis
+    #
+    # Options:
+    #   max_size: Maximum number of entries to keep. When exceeded, the oldest
+    #             entry (by created_at) is evicted. nil = unlimited.
     class Redis
-      def initialize(redis: nil, namespace: nil, **options)
+      def initialize(redis: nil, namespace: nil, max_size: nil, **options)
         @namespace = namespace || SemanticCache.configuration.namespace
         @redis = redis || connect(options)
+        @max_size = max_size
       end
 
-      # Store a cache entry.
+      # Store a cache entry. Evicts the oldest entry if max_size is reached.
       def write(key, entry)
+        evict_oldest! if @max_size && size >= @max_size
+
         full_key = namespaced_key(key)
         data = entry.to_json
 
@@ -122,6 +129,21 @@ module SemanticCache
         @redis.del(full_key)
         @redis.srem(keys_set_key, full_key)
       end
+
+      # Evict the oldest entry (by created_at) to make room for a new one.
+      def evict_oldest!
+        all_entries = entries
+        return if all_entries.empty?
+
+        oldest = all_entries.min_by(&:created_at)
+        key = @redis.smembers(keys_set_key).find do |k|
+          data = @redis.get(k)
+          next false unless data
+
+          Entry.from_json(data).query == oldest.query
+        end
+        delete_raw(key) if key
+      end
     end
   end
 end

data/lib/semantic_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SemanticCache
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semantic-cache
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - stokry