woods 1.0.0

data/lib/woods/builder.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative 'retriever'
+require_relative 'storage/vector_store'
+require_relative 'storage/pgvector'
+require_relative 'storage/qdrant'
+require_relative 'storage/metadata_store'
+require_relative 'storage/graph_store'
+require_relative 'embedding/provider'
+require_relative 'embedding/openai'
+
+module Woods
+  # Builder reads a {Configuration} and instantiates the appropriate adapters,
+  # returning a fully wired {Retriever} ready for use.
+  #
+  # Named presets are provided for common deployment scenarios. All presets can
+  # be further customized with a block passed to {Woods.configure_with_preset}.
+  #
+  # @example Using a preset
+  #   Woods.configure_with_preset(:local)
+  #   result = Woods.retrieve("How does the User model work?")
+  #
+  # @example Using a preset with block customization
+  #   Woods.configure_with_preset(:production) do |config|
+  #     config.embedding_options = { api_key: ENV['OPENAI_API_KEY'] }
+  #     config.vector_store_options = { url: ENV['QDRANT_URL'], collection: 'myapp' }
+  #   end
+  #
+  class Builder # rubocop:disable Metrics/ClassLength
+    # Named presets mapping to default adapter types.
+    #
+    # :local      — fully local, no external services required
+    # :postgresql — pgvector for vectors, OpenAI for embeddings
+    # :production — Qdrant for vectors, OpenAI for embeddings
+    PRESETS = {
+      local: {
+        vector_store: :in_memory,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :ollama
+      },
+      postgresql: {
+        vector_store: :pgvector,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :openai
+      },
+      production: {
+        vector_store: :qdrant,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :openai
+      }
+    }.freeze
+
+    # Build a {Configuration} populated with the named preset's adapter types.
+    #
+    # @param name [Symbol] Preset name — one of :local, :postgresql, or :production
+    # @return [Configuration] A new Configuration with preset values applied
+    # @raise [ArgumentError] if the preset name is not recognized
+    def self.preset_config(name)
+      preset = PRESETS.fetch(name) do
+        raise ArgumentError, "Unknown preset: #{name}. Valid: #{PRESETS.keys.join(', ')}"
+      end
+      config = Configuration.new
+      preset.each { |key, value| config.public_send(:"#{key}=", value) }
+      config
+    end
+
+    # @param config [Configuration] Configuration to read adapter types from
+    def initialize(config = Woods.configuration)
+      @config = config
+    end
+
+    # Build a {Retriever} wired with adapters from the configuration.
+    #
+    # When `cache_enabled` is true, the embedding provider is wrapped with
+    # {Cache::CachedEmbeddingProvider} and the retriever is wrapped with
+    # {Cache::CachedRetriever} for transparent caching of expensive operations.
+    #
+    # @return [Retriever, Cache::CachedRetriever] A fully wired retriever
+    def build_retriever
+      provider = build_embedding_provider
+      cache = build_cache_store
+
+      provider = wrap_with_embedding_cache(provider, cache) if cache
+
+      retriever = Retriever.new(
+        vector_store: build_vector_store,
+        metadata_store: build_metadata_store,
+        graph_store: build_graph_store,
+        embedding_provider: provider
+      )
+
+      cache ? wrap_with_retriever_cache(retriever, cache) : retriever
+    end
+
+    # Instantiate the vector store adapter specified by the configuration.
+    #
+    # @return [Storage::VectorStore::Interface] Vector store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_vector_store
+      case @config.vector_store
+      when :in_memory then Storage::VectorStore::InMemory.new
+      when :pgvector then Storage::VectorStore::Pgvector.new(**(@config.vector_store_options || {}))
+      when :qdrant then Storage::VectorStore::Qdrant.new(**(@config.vector_store_options || {}))
+      else raise ArgumentError, "Unknown vector_store: #{@config.vector_store}"
+      end
+    end
+
+    # Instantiate the embedding provider specified by the configuration.
+    #
+    # @return [Embedding::Provider::Interface] Embedding provider instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_embedding_provider
+      case @config.embedding_provider
+      when :openai then Embedding::Provider::OpenAI.new(**(@config.embedding_options || {}))
+      when :ollama then Embedding::Provider::Ollama.new(**(@config.embedding_options || {}))
+      else raise ArgumentError, "Unknown embedding_provider: #{@config.embedding_provider}"
+      end
+    end
+
+    private
+
+    # Instantiate the metadata store adapter specified by the configuration.
+    #
+    # @return [Storage::MetadataStore::Interface] Metadata store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_metadata_store
+      case @config.metadata_store
+      when :in_memory then Storage::MetadataStore::InMemory.new
+      when :sqlite then Storage::MetadataStore::SQLite.new(**(@config.metadata_store_options || {}))
+      else raise ArgumentError, "Unknown metadata_store: #{@config.metadata_store}"
+      end
+    end
+
+    # Instantiate the graph store adapter specified by the configuration.
+    #
+    # @return [Storage::GraphStore::Interface] Graph store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_graph_store
+      case @config.graph_store
+      when :in_memory then Storage::GraphStore::Memory.new
+      else raise ArgumentError, "Unknown graph_store: #{@config.graph_store}"
+      end
+    end
+
+    # Build a cache store from configuration, or nil if caching is disabled.
+    #
+    # @return [Cache::CacheStore, nil]
+    def build_cache_store
+      return nil unless @config.cache_enabled
+
+      opts = @config.cache_options || {}
+
+      case @config.cache_store
+      when :memory
+        Cache::InMemory.new(max_entries: opts.fetch(:max_entries, 500))
+      when :redis
+        require_relative 'cache/redis_cache_store'
+        Cache::RedisCacheStore.new(redis: opts.fetch(:redis), default_ttl: opts[:default_ttl])
+      when :solid_cache
+        require_relative 'cache/solid_cache_store'
+        Cache::SolidCacheStore.new(cache: opts.fetch(:cache), default_ttl: opts[:default_ttl])
+      when Cache::CacheStore
+        @config.cache_store
+      else
+        raise ArgumentError, "Unknown cache_store: #{@config.cache_store}"
+      end
+    end
+
+    # Wrap an embedding provider with caching.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @param cache [Cache::CacheStore]
+    # @return [Cache::CachedEmbeddingProvider]
+    def wrap_with_embedding_cache(provider, cache)
+      ttls = (@config.cache_options || {}).fetch(:ttl, {})
+      Cache::CachedEmbeddingProvider.new(
+        provider: provider,
+        cache_store: cache,
+        ttl: ttls.fetch(:embeddings, Cache::DEFAULT_TTLS[:embeddings])
+      )
+    end
+
+    # Wrap a retriever with caching.
+    #
+    # @param retriever [Retriever]
+    # @param cache [Cache::CacheStore]
+    # @return [Cache::CachedRetriever]
+    def wrap_with_retriever_cache(retriever, cache)
+      ttls = (@config.cache_options || {}).fetch(:ttl, {})
+      Cache::CachedRetriever.new(
+        retriever: retriever,
+        cache_store: cache,
+        context_ttl: ttls.fetch(:context, Cache::DEFAULT_TTLS[:context])
+      )
+    end
+  end
+end

data/lib/woods/cache/cache_middleware.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'cache_store'
+
+module Woods
+  module Cache
+    # Decorator that wraps an embedding provider with cache-through logic.
+    #
+    # Implements the same {Embedding::Provider::Interface} so it can be
+    # injected transparently in place of the real provider. On cache hit,
+    # the expensive API call (OpenAI, Ollama) is skipped entirely.
+    #
+    # @example
+    #   real_provider = Embedding::Provider::OpenAI.new(api_key: key)
+    #   cached = CachedEmbeddingProvider.new(provider: real_provider, cache_store: store)
+    #   cached.embed("How does User work?")  # API call + cache write
+    #   cached.embed("How does User work?")  # cache hit, no API call
+    #
+    class CachedEmbeddingProvider
+      include Embedding::Provider::Interface
+
+      # @param provider [Embedding::Provider::Interface] The real embedding provider
+      # @param cache_store [CacheStore] Cache backend instance
+      # @param ttl [Integer] TTL for cached embeddings in seconds
+      def initialize(provider:, cache_store:, ttl: DEFAULT_TTLS[:embeddings])
+        @provider = provider
+        @cache_store = cache_store
+        @ttl = ttl
+      end
+
+      # Embed a single text, returning a cached vector when available.
+      #
+      # @param text [String] Text to embed
+      # @return [Array<Float>] Embedding vector
+      def embed(text)
+        key = embedding_key(text)
+        @cache_store.fetch(key, ttl: @ttl) { @provider.embed(text) }
+      end
+
+      # Embed a batch of texts, using cached vectors for any previously seen texts.
+      #
+      # Only texts that are not already cached are sent to the real provider.
+      # Results are merged back in original order.
+      #
+      # @param texts [Array<String>] Texts to embed
+      # @return [Array<Array<Float>>] Embedding vectors (same order as input)
+      def embed_batch(texts)
+        results, misses, miss_indices = partition_cached(texts)
+
+        if misses.any?
+          fresh_vectors = @provider.embed_batch(misses)
+          misses.each_with_index do |text, i|
+            results[miss_indices[i]] = fresh_vectors[i]
+            begin
+              @cache_store.write(embedding_key(text), fresh_vectors[i], ttl: @ttl)
+            rescue StandardError => e
+              warn("[Woods] CachedEmbeddingProvider cache write failed: #{e.message}")
+            end
+          end
+        end
+
+        results
+      end
+
+      # Delegate dimensions to the underlying provider.
+      #
+      # @return [Integer]
+      def dimensions
+        @provider.dimensions
+      end
+
+      # Delegate model_name to the underlying provider.
+      #
+      # @return [String]
+      def model_name
+        @provider.model_name
+      end
+
+      private
+
+      # Split texts into cached hits and uncached misses.
+      #
+      # @param texts [Array<String>]
+      # @return [Array(Array, Array<String>, Array<Integer>)]
+      def partition_cached(texts)
+        results = Array.new(texts.size)
+        misses = []
+        miss_indices = []
+
+        texts.each_with_index do |text, idx|
+          cached = @cache_store.read(embedding_key(text))
+          if cached
+            results[idx] = cached
+          else
+            misses << text
+            miss_indices << idx
+          end
+        end
+
+        [results, misses, miss_indices]
+      end
+
+      # Build a cache key for an embedding text.
+      #
+      # @param text [String]
+      # @return [String]
+      def embedding_key(text)
+        Cache.cache_key(:embeddings, Digest::SHA256.hexdigest(text))
+      end
+    end
+
+    # Decorator that wraps a {Retriever} with result caching.
+    #
+    # Caches the full formatted context output (the most token-expensive artifact)
+    # keyed by query + budget. Also caches the structural context overview
+    # separately with a longer TTL.
+    #
+    # @example
+    #   retriever = Woods::Retriever.new(...)
+    #   cached = CachedRetriever.new(retriever: retriever, cache_store: store)
+    #   cached.retrieve("How does User work?")  # full pipeline + cache
+    #   cached.retrieve("How does User work?")  # instant cache hit
+    #
+    class CachedRetriever
+      # @param retriever [Retriever] The real retriever instance
+      # @param cache_store [CacheStore] Cache backend instance
+      # @param context_ttl [Integer] TTL for formatted context results
+      def initialize(retriever:, cache_store:, context_ttl: DEFAULT_TTLS[:context])
+        @retriever = retriever
+        @cache_store = cache_store
+        @context_ttl = context_ttl
+      end
+
+      # Execute the retrieval pipeline with context-level caching.
+      #
+      # On cache hit, returns a RetrievalResult reconstructed from cached data
+      # without running any pipeline stages. On miss, delegates to the real
+      # retriever and caches the serializable parts of the result.
+      #
+      # @param query [String] Natural language query
+      # @param budget [Integer] Token budget
+      # @return [Retriever::RetrievalResult]
+      def retrieve(query, budget: 8000)
+        key = context_key(query, budget)
+        cached = @cache_store.read(key)
+
+        if cached
+          return Retriever::RetrievalResult.new(
+            context: cached['context'],
+            sources: cached['sources'],
+            classification: nil,
+            strategy: cached['strategy']&.to_sym,
+            tokens_used: cached['tokens_used'],
+            budget: budget,
+            trace: nil
+          )
+        end
+
+        result = @retriever.retrieve(query, budget: budget)
+
+        begin
+          @cache_store.write(key, serialize_result(result), ttl: @context_ttl)
+        rescue StandardError => e
+          warn("[Woods] CachedRetriever cache write failed: #{e.message}")
+        end
+
+        result
+      end
+
+      private
+
+      # Build a cache key for a context result.
+      #
+      # @param query [String]
+      # @param budget [Integer]
+      # @return [String]
+      def context_key(query, budget)
+        Cache.cache_key(:context, query, budget.to_s)
+      end
+
+      # Serialize a RetrievalResult to a JSON-safe hash.
+      #
+      # Only caches the fields needed to reconstruct a useful result:
+      # context string, sources list, strategy, and token count.
+      #
+      # @param result [Retriever::RetrievalResult]
+      # @return [Hash]
+      def serialize_result(result)
+        {
+          'context' => result.context,
+          'sources' => result.sources,
+          'strategy' => result.strategy&.to_s,
+          'tokens_used' => result.tokens_used
+        }
+      end
+    end
+  end
+end

data/lib/woods/cache/cache_store.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'logger'
+
+module Woods
+  module Cache
+    # Default TTLs (in seconds) for each cache domain.
+    #
+    # Embedding vectors are stable (same text → same vector) so they get 24h.
+    # Metadata and structural context refresh on re-extraction (1h).
+    # Search results and formatted context are session-scoped (15min).
+    DEFAULT_TTLS = {
+      embeddings: 86_400,
+      metadata: 3_600,
+      structural: 3_600,
+      search: 900,
+      context: 900
+    }.freeze
+
+    # Build a namespaced cache key from a domain and raw parts.
+    #
+    # @param domain [Symbol] Cache domain (:embeddings, :metadata, etc.)
+    # @param parts [Array<String>] Key components (will be SHA256-hashed if long)
+    # @return [String] Namespaced key
+    def self.cache_key(domain, *parts)
+      raw = parts.join(':')
+      suffix = raw.length > 64 ? Digest::SHA256.hexdigest(raw) : raw
+      "woods:cache:#{domain}:#{suffix}"
+    end
+
+    # Abstract cache store interface.
+    #
+    # All cache backends must implement these methods. The interface is modeled
+    # after ActiveSupport::Cache::Store for familiarity but kept minimal.
+    #
+    # @abstract Subclass and override all public methods.
+    class CacheStore
+      # Read a value from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil] Cached value or nil if missing/expired
+      def read(key)
+        raise NotImplementedError
+      end
+
+      # Write a value to the cache.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache (must be JSON-serializable)
+      # @param ttl [Integer, nil] Time-to-live in seconds (nil = use domain default)
+      # @return [void]
+      def write(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # Delete a key from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        raise NotImplementedError
+      end
+
+      # Check if a key exists and is not expired.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        raise NotImplementedError
+      end
+
+      # Clear cached entries. If namespace is given, only clear that domain.
+      #
+      # @param namespace [Symbol, nil] Cache domain to clear, or nil for all
+      # @return [void]
+      def clear(namespace: nil)
+        raise NotImplementedError
+      end
+
+      # Read-through cache: return cached value or execute block and cache result.
+      #
+      # @note nil is treated as a cache miss. If the wrapped operation legitimately
+      #   returns nil, every call will re-execute the block. Custom backend
+      #   implementers should preserve this semantic — do not return nil for keys
+      #   that were written with a non-nil value. This is acceptable for the
+      #   built-in use cases (embeddings and formatted context are never nil).
+      #
+      # @param key [String] Cache key
+      # @param ttl [Integer, nil] TTL in seconds
+      # @yield Block that computes the value on cache miss
+      # @return [Object] Cached or freshly computed value
+      def fetch(key, ttl: nil)
+        cached = read(key)
+        return cached unless cached.nil?
+
+        value = yield
+        begin
+          write(key, value, ttl: ttl)
+        rescue StandardError => e
+          logger.warn("[Woods] CacheStore#fetch write failed for #{key}: #{e.message}")
+        end
+        value
+      end
+
+      private
+
+      # Return a logger instance (Rails.logger in Rails apps, stderr elsewhere).
+      #
+      # @return [Logger]
+      def logger
+        @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stderr)
+      end
+
+      # Build a wildcard pattern for clearing cache entries.
+      #
+      # @param namespace [Symbol, nil] Cache domain, or nil for all entries
+      # @return [String]
+      def clear_pattern(namespace)
+        namespace ? "woods:cache:#{namespace}:*" : 'woods:cache:*'
+      end
+
+      # Delete a key, silently swallowing any errors.
+      #
+      # Used for cleanup on corrupt/stale entries where failure is acceptable.
+      #
+      # @param key [String]
+      # @return [nil]
+      def delete_silently(key)
+        delete(key)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # In-memory cache store with LRU eviction and TTL support.
+    #
+    # Zero external dependencies. Suitable for single-process use, development,
+    # and as a fallback when Redis/SolidCache are not available. Thread-safe.
+    #
+    # @example
+    #   store = InMemory.new(max_entries: 200)
+    #   store.write("ci:emb:abc", [0.1, 0.2], ttl: 3600)
+    #   store.read("ci:emb:abc") # => [0.1, 0.2]
+    #
+    class InMemory < CacheStore
+      # @param max_entries [Integer] Maximum cached entries before LRU eviction
+      def initialize(max_entries: 500)
+        super()
+        @max_entries = max_entries
+        @entries = {}
+        @access_order = []
+        @mutex = Mutex.new
+      end
+
+      # Read a value, returning nil if missing or expired.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil]
+      def read(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return nil unless entry
+
+          if entry[:expires_at] && Time.now > entry[:expires_at]
+            evict_key(key)
+            return nil
+          end
+
+          touch(key)
+          entry[:value]
+        end
+      end
+
+      # Write a value with optional TTL.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache
+      # @param ttl [Integer, nil] TTL in seconds
+      # @return [void]
+      def write(key, value, ttl: nil)
+        @mutex.synchronize do
+          evict_key(key) if @entries.key?(key)
+
+          if @entries.size >= @max_entries
+            oldest = @access_order.shift
+            @entries.delete(oldest) if oldest
+          end
+
+          expires_at = ttl ? Time.now + ttl : nil
+          @entries[key] = { value: value, expires_at: expires_at }
+          @access_order.push(key)
+        end
+      end
+
+      # Delete a key.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        @mutex.synchronize { evict_key(key) }
+      end
+
+      # Check if a key exists and is not expired.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return false unless entry
+          return false if entry[:expires_at] && Time.now > entry[:expires_at]
+
+          true
+        end
+      end
+
+      # Clear entries. If namespace is given, only clear keys matching that domain.
+      #
+      # @param namespace [Symbol, nil] Domain to clear (:embeddings, :metadata, etc.)
+      # @return [void]
+      def clear(namespace: nil)
+        @mutex.synchronize do
+          if namespace
+            prefix = "woods:cache:#{namespace}:"
+            keys_to_delete = @entries.keys.select { |k| k.start_with?(prefix) }
+            keys_to_delete.each { |k| evict_key(k) }
+          else
+            @entries.clear
+            @access_order.clear
+          end
+        end
+      end
+
+      # Number of entries currently in the cache (for testing/diagnostics).
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+
+      private
+
+      # Remove a key from both the entry hash and access order.
+      #
+      # @param key [String]
+      # @return [void]
+      def evict_key(key)
+        @entries.delete(key)
+        @access_order.delete(key)
+      end
+
+      # Move a key to the end of the access order (most recently used).
+      #
+      # @param key [String]
+      # @return [void]
+      def touch(key)
+        @access_order.delete(key)
+        @access_order.push(key)
+      end
+    end
+  end
+end