vectra-client 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f1fd06b5874c1bc1da1244fb05321cda4a4759e234d9175159c5a6ba7ed8d40
-  data.tar.gz: 9d69e983f4ef5ed4d6bdd58e7a003e06045f3570ba1b3329587f82bcf07902a3
+  metadata.gz: 83a312bb14b8f556d743e0072548a33ec0ac79c9d64768c78b18af3bc7ac6c6b
+  data.tar.gz: 0f0e859dd346e86f095a882e4cb7d47fd1ecf05aa968730b2b3e0d2ff7fa253b
 SHA512:
-  metadata.gz: 7c1911470f96d83470dd98cdc6bb3e6c438a11e71b7317265388d22ae4c3792cea3e595661c927a42587b6008fc891940d511815932b3da478bfeb056ccf8c30
-  data.tar.gz: a3a17643736f8b9a19b92c81a87ce8749a4e55798085e474ef1bc2f13ab9f8c688b2bc7537467a851e59a31cf06390444a064a9d525cff8efb175dbae1de7c7c
+  metadata.gz: ccbc0520ce83f7d2f039a50c0a4b16a9fb59ce21956eb00d5f28270bf61e3ae6c81ab133b02b3ffd1662d29864f5b0ae9c04f60b8e61715f8cbb513b71d48c72
+  data.tar.gz: 38a9b1bbfc4db14005b88d1f29957806f888dc80886c147925fe9dec1643ca67e992aae71258108130ba33b317b999658df5a7756fffe92f0f91bb39b3ba88d1

data/CHANGELOG.md

@@ -1,41 +1,23 @@
 # Changelog
 
-## [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)
-
-### 🎉 Major Feature: Middleware System
+## [v1.1.3](https://github.com/stokry/vectra/tree/v1.1.3) (2026-01-20)
 
-This release introduces a **Rack-style middleware system** for all vector database operations.
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.2...v1.1.3)
 
-#### Added
+- Add `Client#validate!` for configuration/capability checks
+- Add `Client#with_defaults` block helper for temporary default index/namespace
 
-- **Middleware Stack** - All client operations now route through a composable middleware pipeline
-- **5 Built-in Middleware**:
-  - `Vectra::Middleware::Logging` - Structured logs with timing for all operations
-  - `Vectra::Middleware::Retry` - Automatic retry with exponential/linear backoff for transient errors
-  - `Vectra::Middleware::Instrumentation` - Hooks for metrics and APM integration
-  - `Vectra::Middleware::PIIRedaction` - Automatic PII redaction (email, phone, SSN, credit cards)
-  - `Vectra::Middleware::CostTracker` - Track API costs per operation with callbacks
-- **Request/Response Objects** - Type-safe objects with metadata attachment
-- **Extensible Framework** - Create custom middleware by extending `Vectra::Middleware::Base`
-- **Global & Per-Client Middleware** - Apply middleware globally (`Client.use`) or per-instance (`new(middleware: [...])`)
+## [v1.1.2](https://github.com/stokry/vectra/tree/v1.1.2) (2026-01-19)
 
-#### Changed
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.1...v1.1.2)
 
-- All client operations (`upsert`, `query`, `fetch`, `update`, `delete`, `stats`, `list_indexes`, etc.) now route through middleware stack for consistency
-- Middleware has complete visibility into all client operations
+## [v1.1.1](https://github.com/stokry/vectra/tree/v1.1.1) (2026-01-15)
 
-#### Documentation
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.0...v1.1.1)
 
-- Added comprehensive middleware section to README
-- Created `examples/middleware_demo.rb` demonstrating all 5 built-in middleware
-- Full YARD documentation for all middleware classes
-- Published [middleware guide](https://dev.to/stokry/rack-style-middleware-for-vector-databases-in-ruby-vectra-client-110-2jh3) on Dev.to
-
-#### Migration Notes
+## [v1.1.0](https://github.com/stokry/vectra/tree/v1.1.0) (2026-01-15)
 
-No breaking changes. Middleware is opt-in - existing code works without modification.
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.8...v1.1.0)
 
 ## [v1.0.8](https://github.com/stokry/vectra/tree/v1.0.8) (2026-01-14)
 

data/README.md

@@ -226,6 +226,8 @@ This will:
 - **Update the model** to include `ProductVector`
 - **Append to `config/vectra.yml`** with index metadata (no API keys)
 
+When `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` in that Rails app will automatically use that entry's `index` (and `namespace` if present) as its defaults, so you can usually omit `index:` when calling `upsert` / `query` / `text_search`.
+
 ### Complete Rails Guide
 
 For a complete step-by-step guide including:

data/docs/_layouts/home.html

@@ -55,7 +55,7 @@
   <!-- Hero Section -->
   <section class="tma-hero">
     <div class="tma-hero__container">
-      <span class="tma-hero__badge">v1.1.0 — Hybrid Search, Rails Generator & Middleware</span>
+      <span class="tma-hero__badge">v1.1.1 — Hybrid Search, Rails Generator, Middleware & Text Search</span>
       <h1 class="tma-hero__title">
         Vector Databases,<br>
         <span class="tma-hero__title-gradient">Unified for Ruby.</span>

data/docs/_layouts/page.html

@@ -39,6 +39,12 @@
         <span class="tma-nav__toggle-line"></span>
       </button>
       <ul class="tma-nav__menu" id="nav-menu">
+        <li class="tma-nav__search-wrapper">
+          <div class="tma-search">
+            <input type="search" id="search-input" class="tma-search__input" placeholder="Search docs..." aria-label="Search documentation">
+            <div id="search-results" class="tma-search__results"></div>
+          </div>
+        </li>
         <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
         <li><a href="{{ site.baseurl }}/guides/recipes" class="tma-nav__link">Recipes</a></li>
         <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
@@ -122,6 +128,9 @@
     </div>
   </footer>
 
+  <!-- Simple Jekyll Search -->
+  <script src="https://cdn.jsdelivr.net/npm/simple-jekyll-search@1.10.0/dest/simple-jekyll-search.min.js"></script>
+  
   <script>
     document.addEventListener('DOMContentLoaded', function() {
       const navToggle = document.querySelector('.tma-nav__toggle');
@@ -155,6 +164,19 @@
           }
         });
       }
+
+      // Initialize search
+      if (typeof SimpleJekyllSearch !== 'undefined') {
+        SimpleJekyllSearch({
+          searchInput: document.getElementById('search-input'),
+          resultsContainer: document.getElementById('search-results'),
+          json: '{{ site.baseurl }}/search.json',
+          searchResultTemplate: '<div class="tma-search__result"><a href="{url}" class="tma-search__result-link"><span class="tma-search__result-title">{title}</span><span class="tma-search__result-excerpt">{excerpt}</span></a></div>',
+          noResultsText: '<div class="tma-search__no-results">No results found</div>',
+          fuzzy: true,
+          limit: 10
+        });
+      }
     });
   </script>
 </body>

data/docs/api/cheatsheet.md

@@ -49,6 +49,25 @@ client.upsert(vectors: [...])
 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])
+```
+
 ### Upsert
 
 ```ruby
@@ -193,6 +212,14 @@ else
 end
 ```
 
+For fast health checks you can temporarily lower the timeout:
+
+```ruby
+status = client.with_timeout(0.5) do |c|
+  c.ping
+end
+```
+
 ### Ping (with latency)
 
 ```ruby

data/docs/api/methods.md

@@ -36,6 +36,8 @@ client = Vectra::Client.new(
 )
 ```
 
+In a Rails app that uses the `vectra:index` generator, if `config/vectra.yml` contains exactly one entry, `Vectra::Client.new` will automatically use that entry's `index` (and `namespace` if present) as its defaults. This allows you to omit `index:` in most calls (`upsert`, `query`, `text_search`, etc.).
+
 ---
 
 ### `client.upsert(index:, vectors:, namespace: nil)`
@@ -402,6 +404,77 @@ puts "Latency: #{status[:latency_ms]}ms"
 
 ---
 
+### `client.with_timeout(seconds) { ... }`
+
+Temporarily override the client's request timeout inside a block.
+
+**Parameters:**
+- `seconds` (Float) - Temporary timeout in seconds
+
+**Returns:** Block result
+
+**Example (fast health check in Rails controller):**
+```ruby
+status = client.with_timeout(0.5) do |c|
+  c.ping
+end
+
+render json: status, status: status[:healthy] ? :ok : :service_unavailable
+```
+
+After the block finishes (even if it raises), the previous `config.timeout` value is restored.
+
+---
+
+### `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.health_check`
 
 Detailed health check with provider-specific information.

data/docs/api/overview.md

@@ -10,15 +10,15 @@ permalink: /api/overview/
 
 ```ruby
 client = Vectra::Client.new(
-  provider: :pinecone,        # Required: :pinecone, :qdrant, :weaviate, :pgvector
+  provider: :pinecone,        # Required: :pinecone, :qdrant, :weaviate, :pgvector, :memory
   api_key: 'your-api-key',    # Required for cloud providers
-  index_name: 'my-index',     # Optional, provider-dependent
-  host: 'localhost',          # For self-hosted providers
-  port: 6333,                 # For self-hosted providers
-  environment: 'us-west-4'    # For Pinecone
+  index: 'my-index',          # Optional default index
+  namespace: 'tenant-1'       # Optional default namespace
 )
 ```
 
+In Rails, if you use the `vectra:index` generator and `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` will automatically pick that entry's `index` (and `namespace` if present) as defaults.
+
 ## Core Methods
 
 ### `upsert(vectors:)`
@@ -138,6 +138,31 @@ results = client.hybrid_search(
 
 **Provider Support:** Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️
 
+### `text_search(index:, text:, top_k:)`
+
+Text-only search (keyword search without requiring embeddings).
+
+**Parameters:**
+- `index` (String) - Index/collection name (uses client's default index when omitted)
+- `text` (String) - Text query for keyword search
+- `top_k` (Integer) - Number of results (default: 10)
+- `namespace` (String, optional) - Namespace
+- `filter` (Hash, optional) - Metadata filter
+- `include_values` (Boolean) - Include vector values (default: false)
+- `include_metadata` (Boolean) - Include metadata (default: true)
+
+**Example:**
+```ruby
+results = client.text_search(
+  index: 'products',
+  text: 'iPhone 15 Pro',
+  top_k: 10,
+  filter: { category: 'electronics' }
+)
+```
+
+**Provider Support:** Qdrant ✅ (BM25), Weaviate ✅ (BM25), pgvector ✅ (PostgreSQL full-text), Memory ✅, Pinecone ❌
+
 ### `healthy?`
 
 Quick health check - returns true if provider connection is healthy.
@@ -151,6 +176,12 @@ if client.healthy?
 end
 ```
 
+You can also run faster checks with a temporary timeout:
+
+```ruby
+fast_ok = client.with_timeout(0.5) { |c| c.healthy? }
+```
+
 ### `ping`
 
 Ping provider and get connection health status with latency.

data/docs/assets/style.css

@@ -165,6 +165,118 @@ body {
   border-color: var(--tma-color-border-hover);
 }
 
+.tma-nav__search-wrapper {
+  position: relative;
+  margin-right: var(--tma-spacing-md);
+}
+
+.tma-search {
+  position: relative;
+}
+
+.tma-search__input {
+  width: 240px;
+  padding: var(--tma-spacing-sm) var(--tma-spacing-md);
+  padding-left: 2.5rem;
+  background: var(--tma-color-bg-tertiary);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-sm);
+  color: var(--tma-color-text-primary);
+  font-size: 0.9rem;
+  font-family: var(--tma-font-family-primary);
+  transition: all var(--tma-transition-fast);
+  outline: none;
+}
+
+.tma-search__input::placeholder {
+  color: var(--tma-color-text-muted);
+}
+
+.tma-search__input:focus {
+  width: 320px;
+  border-color: var(--tma-color-accent-primary);
+  background: var(--tma-color-bg-elevated);
+  box-shadow: 0 0 0 3px var(--tma-color-accent-muted);
+}
+
+.tma-search {
+  position: relative;
+}
+
+.tma-search::before {
+  content: '🔍';
+  position: absolute;
+  left: var(--tma-spacing-md);
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--tma-color-text-muted);
+  pointer-events: none;
+  z-index: 1;
+  font-size: 0.9rem;
+}
+
+.tma-search__results {
+  position: absolute;
+  top: calc(100% + var(--tma-spacing-xs));
+  left: 0;
+  right: 0;
+  max-width: 500px;
+  max-height: 400px;
+  overflow-y: auto;
+  background: var(--tma-color-bg-elevated);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-md);
+  box-shadow: var(--tma-shadow-lg);
+  z-index: 1000;
+  display: none;
+}
+
+.tma-search__results:not(:empty) {
+  display: block;
+}
+
+.tma-search__result {
+  border-bottom: 1px solid var(--tma-color-border);
+}
+
+.tma-search__result:last-child {
+  border-bottom: none;
+}
+
+.tma-search__result-link {
+  display: block;
+  padding: var(--tma-spacing-md);
+  text-decoration: none;
+  color: var(--tma-color-text-primary);
+  transition: background var(--tma-transition-fast);
+}
+
+.tma-search__result-link:hover {
+  background: var(--tma-color-bg-hover);
+}
+
+.tma-search__result-title {
+  display: block;
+  font-weight: 600;
+  font-size: 0.95rem;
+  color: var(--tma-color-text-primary);
+  margin-bottom: var(--tma-spacing-xs);
+}
+
+.tma-search__result-excerpt {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--tma-color-text-secondary);
+  line-height: 1.5;
+}
+
+.tma-search__no-results {
+  padding: var(--tma-spacing-lg);
+  text-align: center;
+  color: var(--tma-color-text-muted);
+  font-size: 0.9rem;
+}
+
 .tma-nav__toggle {
   display: none;
   flex-direction: column;
@@ -1261,6 +1373,25 @@ code {
     justify-content: center;
   }
   
+  .tma-nav__search-wrapper {
+    width: 100%;
+    margin-right: 0;
+    margin-bottom: var(--tma-spacing-md);
+  }
+  
+  .tma-search__input {
+    width: 100%;
+  }
+  
+  .tma-search__input:focus {
+    width: 100%;
+  }
+  
+  .tma-search__results {
+    max-width: 100%;
+    right: 0;
+  }
+  
   .tma-features,
   .tma-providers {
     padding: var(--tma-spacing-xl) var(--tma-spacing-md);

data/docs/guides/rails-integration.md

@@ -99,6 +99,8 @@ This will:
 - Update `app/models/product.rb` to include the concern
 - Add configuration to `config/vectra.yml`
 
+When `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` in this Rails app will automatically use that entry's `index` (and `namespace` if present) as its defaults. That means you can usually omit `index:` when calling `upsert`, `query`, `hybrid_search`, or `text_search`.
+
 ### Run Migrations
 
 ```bash

data/docs/search.json

@@ -0,0 +1,26 @@
+---
+layout: null
+---
+[
+  {% assign first = true %}
+  {% for page in site.pages %}
+    {% unless page.url == '/' or page.url == '/search.json' or page.url contains '/assets/' or page.url contains '/404' or page.url contains '/feed' or page.url contains '/sitemap' or page.url contains '/robots' or page.url contains '/index.html' or page.url contains '/index.md' %}
+      {% unless first %},{% endunless %}
+      {
+        "title": {{ page.title | default: page.url | jsonify }},
+        "url": {{ page.url | jsonify }},
+        "excerpt": {{ page.content | strip_html | truncatewords: 30 | default: "" | jsonify }}
+      }
+      {% assign first = false %}
+    {% endunless %}
+  {% endfor %}
+  {% for post in site.posts %}
+    {% unless first %},{% endunless %}
+    {
+      "title": {{ post.title | jsonify }},
+      "url": {{ post.url | jsonify }},
+      "excerpt": {{ post.content | strip_html | truncatewords: 30 | default: "" | jsonify }}
+    }
+    {% assign first = false %}
+  {% endfor %}
+]

data/lib/vectra/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 # Ensure HealthCheck is loaded before Client
 require_relative "health_check" unless defined?(Vectra::HealthCheck)
 require_relative "configuration" unless defined?(Vectra::Configuration)
@@ -42,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
       #
@@ -89,6 +94,7 @@ module Vectra
       @provider = build_provider
       @default_index = options[:index]
       @default_namespace = options[:namespace]
+      apply_rails_vectra_defaults! if @default_index.nil? && @default_namespace.nil?
       @middleware = build_middleware_stack(options[:middleware])
     end
 
@@ -618,6 +624,43 @@ 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
+
     # Chainable query builder
     #
     # @api public
@@ -745,6 +788,90 @@ module Vectra
       Middleware::Stack.new(@provider, all_middleware)
     end
 
+    def apply_rails_vectra_defaults!
+      return unless rails_root_available?
+
+      entry = load_single_vectra_entry
+      return unless entry
+
+      apply_vectra_defaults_from(entry)
+    rescue StandardError => e
+      log_error("Failed to infer default index/namespace from config/vectra.yml", e)
+    end
+
+    def rails_root_available?
+      defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+    end
+
+    def vectra_config_path
+      File.join(Rails.root.to_s, "config", "vectra.yml")
+    end
+
+    def load_single_vectra_entry
+      path = vectra_config_path
+      return unless File.exist?(path)
+
+      raw = File.read(path)
+      data = YAML.safe_load(raw, permitted_classes: [], aliases: true) || {}
+      return unless data.is_a?(Hash) && data.size == 1
+
+      data.values.first || {}
+    end
+
+    def apply_vectra_defaults_from(entry)
+      index = entry["index"] || entry[:index]
+      namespace = entry["namespace"] || entry[:namespace]
+
+      @default_index = index if @default_index.nil? && index.is_a?(String) && !index.empty?
+      @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)
@@ -811,6 +938,22 @@ module Vectra
       config.logger.debug("[Vectra] #{data.inspect}") if data
     end
 
+    # Temporarily override request timeout within a block.
+    #
+    # This updates the client's configuration timeout for the duration
+    # of the block and then restores the previous value.
+    #
+    # @param seconds [Float] temporary timeout in seconds
+    # @yield [Client] yields self with overridden timeout
+    # @return [Object] block result
+    def with_timeout(seconds)
+      previous = config.timeout
+      config.timeout = seconds
+      yield self
+    ensure
+      config.timeout = previous
+    end
+
     # Temporarily override default index within a block.
     #
     # @param index [String] temporary index name
@@ -851,7 +994,29 @@ module Vectra
       end
     end
 
-    public :with_index, :with_namespace, :with_index_and_namespace
+    # 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
+
+    public :with_index, :with_namespace, :with_index_and_namespace, :with_defaults, :with_timeout
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/vectra/health_check.rb

@@ -31,7 +31,7 @@ module Vectra
 
       # For health checks we bypass client middleware and call the provider
       # directly to avoid interference from custom stacks.
-      indexes = with_timeout(timeout) { provider.list_indexes }
+      indexes = healthcheck_with_timeout(timeout) { provider.list_indexes }
       index_name = index || indexes.first&.dig(:name)
 
       result = base_result(start_time, indexes)
@@ -53,7 +53,7 @@ module Vectra
 
     private
 
-    def with_timeout(seconds, &)
+    def healthcheck_with_timeout(seconds, &)
       Timeout.timeout(seconds, &)
     rescue Timeout::Error
       raise Vectra::TimeoutError, "Health check timed out after #{seconds}s"
@@ -72,7 +72,7 @@ module Vectra
     def add_index_stats(result, index_name, include_stats, timeout)
       return unless include_stats && index_name
 
-      stats = with_timeout(timeout) { provider.stats(index: index_name) }
+      stats = healthcheck_with_timeout(timeout) { provider.stats(index: index_name) }
       result[:index] = index_name
       result[:stats] = {
         vector_count: stats[:total_vector_count],

data/lib/vectra/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Mijo Kristo
@@ -289,6 +289,7 @@ files:
 - docs/providers/qdrant.md
 - docs/providers/selection.md
 - docs/providers/weaviate.md
+- docs/search.json
 - examples/GRAFANA_QUICKSTART.md
 - examples/README.md
 - examples/active_record_demo.rb