vectra-client 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f59705f200c8a164cc9303e6761776af49e4a81a88f101eae2e371eccca8807
-  data.tar.gz: 217dd74d00151f3ba6e94ed80718999656f9616b84e843dd937197cee612540a
+  metadata.gz: c2ed5842cd4c611fd0c140abc8925a2d13577c4f2094dbc71c7b2772aceda9e4
+  data.tar.gz: da3005805b97d5b36c632d3e2c34ad9a3966eb65b09ce2f5f84911858c2d34d5
 SHA512:
-  metadata.gz: 8e62f19e82dfb88a14ae50f7cee6afdd8d058ece9972de8f447ba3cc881420d401cfd0d3a093d299e8273795958085349a8d3e6416ecd429f50ea2a05103dea3
-  data.tar.gz: ace8ecc519dc588f917e6b29721ed9cfa3ff9b3f3fd7b3e82911233ed7d6e59a9f443e81ae9c0d20dd4891f904d8497cb506064964b00b3dc7587f12137e12bf
+  metadata.gz: bb3324f260afb42c5e03356f8d09c902571fcaddc39969541c918523c4ebadbdb8dadf35764d9d04cce2b308ee4aa18d9f7c3266690a1a728ceeecb9908a3622
+  data.tar.gz: adca9a174757547d1306dbaa727069fa1954a8dc40b101c1cb378bfb3663c94ad7ec0a35082ea578ef4dd4a7ab53477bdfde6dd258623c83e161eb8c6cff2b42

data/CHANGELOG.md

@@ -1,25 +1,24 @@
 # Changelog
 
+## [v1.1.4](https://github.com/stokry/vectra/tree/v1.1.4) (2026-01-20)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.3...v1.1.4)
+
+- Add `Client#valid?` – non-raising validation (returns true/false)
+- Add `Client#for_tenant` – multi-tenant block helper for namespace isolation
+
+## [v1.1.3](https://github.com/stokry/vectra/tree/v1.1.3) (2026-01-20)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.2...v1.1.3)
+
+## [v1.1.2](https://github.com/stokry/vectra/tree/v1.1.2) (2026-01-19)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.1...v1.1.2)
+
 ## [v1.1.1](https://github.com/stokry/vectra/tree/v1.1.1) (2026-01-15)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.1.0...v1.1.1)
 
-### Added
-- **Text Search Support** - New `text_search` method for keyword-only search without requiring embeddings
-  - Qdrant: BM25 text search
-  - Weaviate: BM25 text search via GraphQL
-  - pgvector: PostgreSQL full-text search (`to_tsvector`, `plainto_tsquery`, `ts_rank`)
-  - Memory: Simple keyword matching (for testing)
-  - Raises `UnsupportedFeatureError` for Pinecone (use sparse vectors instead)
-- **Documentation Search** - Added search functionality to documentation site with `simple-jekyll-search`
-  - Client-side search with fuzzy matching
-  - Search index auto-generated from all documentation pages
-  - Responsive search UI in navigation
-
-### Changed
-- Updated API documentation to include `text_search` method in overview and cheatsheet
-- Enhanced documentation with text search examples and use cases
-
 ## [v1.1.0](https://github.com/stokry/vectra/tree/v1.1.0) (2026-01-15)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.8...v1.1.0)

data/docs/api/cheatsheet.md

@@ -51,6 +51,36 @@ client.query(vector: query_embedding, top_k: 10)
 
 In a Rails app with `config/vectra.yml` generated by `rails generate vectra:index`, if that YAML file contains only one entry, `Vectra::Client.new` will automatically use that entry's `index` (and `namespace`, if present) as defaults.
 
+### Temporary defaults (block-scoped)
+
+```ruby
+client.with_defaults(index: "products", namespace: "tenant-2") do |c|
+  c.upsert(vectors: [...])
+  c.query(vector: query_embedding, top_k: 10)
+end
+```
+
+### Validate client config & capabilities
+
+```ruby
+client.validate!
+client.validate!(require_default_index: true)
+client.validate!(features: [:text_search])
+
+# Non-raising: returns true/false
+client.valid?
+client.valid?(require_default_index: true)
+```
+
+### Multi-tenant (for_tenant)
+
+```ruby
+client.for_tenant("acme", namespace_prefix: "tenant_") do |c|
+  c.upsert(vectors: [...])
+  c.query(vector: query_embedding, top_k: 10)
+end
+```
+
 ### Upsert
 
 ```ruby

data/docs/api/methods.md

@@ -426,6 +426,94 @@ After the block finishes (even if it raises), the previous `config.timeout` valu
 
 ---
 
+### `client.validate!(require_default_index: false, require_default_namespace: false, features: [])`
+
+Validate the client configuration and (optionally) your defaults and provider feature support.
+
+This is useful in boot-time checks (Rails initializers), health endpoints, and CI.
+
+**Parameters:**
+- `require_default_index` (Boolean) - Require `client.default_index` to be set
+- `require_default_namespace` (Boolean) - Require `client.default_namespace` to be set
+- `features` (Array<Symbol> or Symbol) - Provider features (methods) that must be supported (e.g. `:text_search`)
+
+**Returns:** `Vectra::Client` (self)
+
+**Raises:** `Vectra::ConfigurationError` when validation fails
+
+**Example:**
+```ruby
+# Ensure client is configured
+client.validate!
+
+# Ensure calls can omit index:
+client.validate!(require_default_index: true)
+
+# Ensure provider supports text_search:
+client.validate!(features: [:text_search])
+```
+
+---
+
+### `client.with_defaults(index: ..., namespace: ...) { ... }`
+
+Temporarily override the client's **default index and/or namespace** inside a block.
+
+Unlike `with_index_and_namespace`, this helper accepts keyword arguments and only overrides what you pass.
+
+**Returns:** Block result
+
+**Example:**
+```ruby
+client.with_defaults(index: "products", namespace: "tenant-2") do |c|
+  c.upsert(vectors: [...]) # uses products/tenant-2
+  c.query(vector: embedding, top_k: 10)
+end
+
+# Previous defaults are restored after the block.
+```
+
+---
+
+### `client.valid?(require_default_index: false, require_default_namespace: false, features: [])`
+
+Non-raising validation. Returns `true` if the client passes `validate!`, `false` otherwise. Accepts the same options as `validate!`.
+
+**Returns:** `Boolean`
+
+**Example:**
+```ruby
+next unless client.valid?
+client.upsert(vectors: [...])
+
+# With same options as validate!
+client.valid?(require_default_index: true)
+client.valid?(features: [:text_search])
+```
+
+---
+
+### `client.for_tenant(tenant_id, namespace_prefix: "tenant_") { ... }`
+
+Multi-tenant block helper. Temporarily sets the default namespace to `"#{namespace_prefix}#{tenant_id}"`, yields the client, then restores the previous namespace. `tenant_id` can be a string, symbol, or anything responding to `to_s`.
+
+**Parameters:**
+- `tenant_id` (String, Symbol, #to_s) - Tenant identifier
+- `namespace_prefix` (String) - Prefix for namespace (default: `"tenant_"`)
+
+**Returns:** Block result
+
+**Example:**
+```ruby
+client.for_tenant("acme", namespace_prefix: "tenant_") do |c|
+  c.upsert(vectors: [...])
+  c.query(vector: embedding, top_k: 10)
+end
+# All operations use namespace "tenant_acme"; previous default restored after block.
+```
+
+---
+
 ### `client.health_check`
 
 Detailed health check with provider-specific information.

data/lib/vectra/client.rb

@@ -44,6 +44,9 @@ module Vectra
 
     attr_reader :config, :provider, :default_index, :default_namespace
 
+    DEFAULT_UNSET = Object.new.freeze
+    private_constant :DEFAULT_UNSET
+
     class << self
       # Get the global middleware stack
       #
@@ -621,6 +624,67 @@ module Vectra
       result
     end
 
+    # Validate the client configuration and provider capabilities.
+    #
+    # This is a convenience wrapper around `config.validate!` that can also
+    # validate your defaults and provider feature support.
+    #
+    # @param require_default_index [Boolean] require default index to be set
+    # @param require_default_namespace [Boolean] require default namespace to be set
+    # @param features [Array<Symbol>, Symbol] provider features (methods) required, e.g. :text_search
+    # @return [true]
+    # @raise [ConfigurationError] when client is misconfigured
+    #
+    # @example Basic validation
+    #   client.validate! # => client
+    #
+    # @example Ensure you can call methods without passing index:
+    #   client.validate!(require_default_index: true)
+    #
+    # @example Ensure provider supports text search:
+    #   client.validate!(features: [:text_search])
+    #
+    def validate!(require_default_index: false, require_default_namespace: false, features: [])
+      errors = []
+
+      append_client_config_errors(errors)
+      append_client_provider_errors(errors)
+      append_client_default_errors(
+        errors,
+        require_default_index: require_default_index,
+        require_default_namespace: require_default_namespace
+      )
+      append_client_feature_errors(errors, features: features)
+
+      raise ConfigurationError, client_validation_message(errors) if errors.any?
+
+      self
+    end
+
+    # Non-raising validation. Returns true if client passes validate!, false otherwise.
+    #
+    # Accepts the same options as validate!.
+    #
+    # @param require_default_index [Boolean] require default index to be set
+    # @param require_default_namespace [Boolean] require default namespace to be set
+    # @param features [Array<Symbol>, Symbol] provider features required, e.g. :text_search
+    # @return [Boolean]
+    #
+    # @example
+    #   next unless client.valid?
+    #   client.upsert(vectors: [...])
+    #
+    def valid?(require_default_index: false, require_default_namespace: false, features: [])
+      validate!(
+        require_default_index: require_default_index,
+        require_default_namespace: require_default_namespace,
+        features: features
+      )
+      true
+    rescue ConfigurationError
+      false
+    end
+
     # Chainable query builder
     #
     # @api public
@@ -786,6 +850,52 @@ module Vectra
       @default_namespace = namespace if @default_namespace.nil? && namespace.is_a?(String) && !namespace.empty?
     end
 
+    def append_client_config_errors(errors)
+      config.validate!
+    rescue ConfigurationError, UnsupportedProviderError => e
+      errors << e.message
+    end
+
+    def append_client_provider_errors(errors)
+      errors << "Provider is not initialized" if provider.nil?
+    end
+
+    def append_client_default_errors(errors, require_default_index:, require_default_namespace:)
+      append_default_index_error(errors) if require_default_index
+      append_default_namespace_error(errors) if require_default_namespace
+    end
+
+    def append_default_index_error(errors)
+      if default_index.nil? || (default_index.respond_to?(:empty?) && default_index.empty?)
+        errors << "Default index is not set (pass `index:` to Vectra::Client.new, or set it via config/vectra.yml in Rails)"
+      elsif !default_index.is_a?(String)
+        errors << "Default index must be a String"
+      end
+    end
+
+    def append_default_namespace_error(errors)
+      if default_namespace.nil? || (default_namespace.respond_to?(:empty?) && default_namespace.empty?)
+        errors << "Default namespace is not set (pass `namespace:` to Vectra::Client.new, or set it via config/vectra.yml in Rails)"
+      elsif !default_namespace.is_a?(String)
+        errors << "Default namespace must be a String"
+      end
+    end
+
+    def append_client_feature_errors(errors, features:)
+      return if provider.nil?
+
+      Array(features).compact.each do |feature|
+        method = feature.to_sym
+        next if provider.respond_to?(method)
+
+        errors << "Provider does not support `#{method}`"
+      end
+    end
+
+    def client_validation_message(errors)
+      "Client validation failed:\n- #{errors.join("\n- ")}"
+    end
+
     def validate_index!(index)
       raise ValidationError, "Index name cannot be nil" if index.nil?
       raise ValidationError, "Index name must be a string" unless index.is_a?(String)
@@ -908,7 +1018,47 @@ module Vectra
       end
     end
 
-    public :with_index, :with_namespace, :with_index_and_namespace, :with_timeout
+    # Temporarily override default index and/or namespace within a block.
+    #
+    # Unlike `with_index_and_namespace`, this method accepts keyword arguments
+    # and only overrides the values you pass.
+    #
+    # @param index [String, nil] temporary index name (omit to keep current)
+    # @param namespace [String, nil] temporary namespace (omit to keep current)
+    # @yield [Client] yields self with overridden defaults
+    # @return [Object] block result
+    def with_defaults(index: DEFAULT_UNSET, namespace: DEFAULT_UNSET)
+      previous_index = @default_index
+      previous_namespace = @default_namespace
+
+      @default_index = index unless index.equal?(DEFAULT_UNSET)
+      @default_namespace = namespace unless namespace.equal?(DEFAULT_UNSET)
+
+      yield self
+    ensure
+      @default_index = previous_index
+      @default_namespace = previous_namespace
+    end
+
+    # Multi-tenant block helper: temporarily sets default namespace to +"#{namespace_prefix}#{tenant_id}"+.
+    #
+    # @param tenant_id [String, Symbol, #to_s] tenant identifier
+    # @param namespace_prefix [String] prefix for namespace (default: "tenant_")
+    # @yield [Client] yields self with overridden namespace
+    # @return [Object] block result
+    #
+    # @example
+    #   client.for_tenant("acme", namespace_prefix: "tenant_") do |c|
+    #     c.upsert(vectors: [...])
+    #     c.query(vector: emb, top_k: 10)
+    #   end
+    #
+    def for_tenant(tenant_id, namespace_prefix: "tenant_")
+      ns = "#{namespace_prefix}#{tenant_id}"
+      with_namespace(ns) { yield self }
+    end
+
+    public :with_index, :with_namespace, :with_index_and_namespace, :with_defaults, :with_timeout, :for_tenant
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "1.1.2"
+  VERSION = "1.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Mijo Kristo