vectra-client 0.4.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d48b8a6205df9a0d6545e3772e26da09f826f03d56751a6fa997e1a73d89f1
-  data.tar.gz: 25dc65ad327e03e7912a0b938739b6acf1d6708efd8fa41773d9bbae1053e3dc
+  metadata.gz: b28b595dca76f398f7214341af084ae1f344087d09f2a3933228bf8d006f4ec5
+  data.tar.gz: 9e5c7344a204724914746545042d30618b01c23287178f1abce8e75050c9628e
 SHA512:
-  metadata.gz: 68fc7d7a2c941733bb8f42007dffa52989daedeb362da62c094d05dec7d02f8ca6d7ca8763194e9b51b4ecfe3f7a6e8db4418c7589caab31943f055f75f4c48a
-  data.tar.gz: f40ab28eb011943d4961e22c5d31b5a816a81cea1a2bf6afa238004adaa1cdd8558f10b0ee8d56376d6fc737788b16fc1acb7088778d8461ecb3a8db2ff85580
+  metadata.gz: ecece93b7ab73710d5ac3718a8c6829b8a93d51e801aa4ad93ce85ab61fd129fed6ec66e138a1427fe2b2fbc9d9501998d38c1362363a1790b650a0d3aedfc66
+  data.tar.gz: 8b10e152ca8fcf573bf45e61cd887c9648c17ace9d8516f660448178c33e1904dce700271f33dd0b64374a63702f70c3f0e75a5ea40b673ba223e2d4c1ff117d

data/CHANGELOG.md

@@ -1,19 +1,17 @@
 # Changelog
 
-## [v0.4.0](https://github.com/stokry/vectra/tree/v0.4.0) (2026-01-12)
-
-### Added
-- Memory provider for in-memory vector storage
-- QueryBuilder for chainable query API
-- Batch operations with concurrent processing
-- Vector normalization methods (L2, L1)
-- Enhanced error message extraction
+## [v1.0.1](https://github.com/stokry/vectra/tree/v1.0.1) (2026-01-13)
 
 ### Fixed
-- Weaviate DELETE request query parameters
-- Qdrant error message extraction from nested status
-- Client ping error info capture
-- Credential rotation timeout parameter handling
+- Fix RuboCop violations in index generator
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.0...v1.0.1)
+
+## [v1.0.0](https://github.com/stokry/vectra/tree/v1.0.0) (2026-01-12)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.4.0...v1.0.0)
+
+## [v0.4.0](https://github.com/stokry/vectra/tree/v0.4.0) (2026-01-12)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v0.3.4...v0.4.0)
 

data/README.md

@@ -1,13 +1,32 @@
-# Vectra
-
-[![Gem Version](https://badge.fury.io/rb/vectra-client.svg)](https://rubygems.org/gems/vectra-client)
-[![CI](https://github.com/stokry/vectra/actions/workflows/ci.yml/badge.svg)](https://github.com/stokry/vectra/actions)
-[![codecov](https://codecov.io/gh/stokry/vectra/branch/main/graph/badge.svg)](https://codecov.io/gh/stokry/vectra)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**A unified Ruby client for vector databases.** Write once, switch providers seamlessly.
-
-📖 **Documentation:** [vectra-docs.netlify.app](https://vectra-docs.netlify.app/)
+# Vectra client
+
+<p align="center">
+  <img src="docs/assets/readme-new.png" alt="Vectra – Unified Ruby client for vector databases" width="340">
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/vectra-client">
+    <img src="https://badge.fury.io/rb/vectra-client.svg" alt="Gem Version">
+  </a>
+  <a href="https://github.com/stokry/vectra/actions">
+    <img src="https://github.com/stokry/vectra/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
+  <a href="https://codecov.io/gh/stokry/vectra">
+    <img src="https://codecov.io/gh/stokry/vectra/branch/main/graph/badge.svg" alt="codecov">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <strong>A unified Ruby client for vector databases.</strong><br>
+  Write once, switch providers seamlessly.
+</p>
+
+<p align="center">
+  📖 <strong>Documentation:</strong> <a href="https://vectra-docs.netlify.app/">vectra-docs.netlify.app</a>
+</p>
 
 ## Supported Providers
 
@@ -81,6 +100,15 @@ end
 # Ping with latency
 status = client.ping
 puts "Provider: #{status[:provider]}, Latency: #{status[:latency_ms]}ms"
+
+# Hybrid search (semantic + keyword)
+# Supported by: Qdrant, Weaviate, Pinecone, pgvector
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7  # 70% semantic, 30% keyword
+)
 ```
 
 ## Provider Examples
@@ -108,13 +136,51 @@ client = Vectra.pgvector(connection_url: 'postgres://user:pass@localhost/mydb')
 client = Vectra.memory
 ```
 
+## Architecture Overview
+
+```mermaid
+graph TB
+    A[Vectra Client] --> B[Unified API]
+    B --> C[Pinecone]
+    B --> D[Qdrant]
+    B --> E[Weaviate]
+    B --> F[pgvector]
+    B --> G[Memory]
+    
+    H[Production Patterns] --> I[Circuit Breaker]
+    H --> J[Rate Limiter]
+    H --> K[Retry Logic]
+    H --> L[Instrumentation]
+    
+    A --> H
+    
+    style A fill:#05df72
+    style B fill:#2ee889
+    style H fill:#04b85e
+```
+
 ## Features
 
-- **Provider Agnostic** - Switch providers with one line change
-- **Production Ready** - Ruby 3.2+, 95%+ test coverage
-- **Resilient** - Retry logic with exponential backoff
-- **Observable** - Datadog & New Relic instrumentation
-- **Rails Ready** - ActiveRecord integration with `has_vector` DSL
+- **🔌 Provider Agnostic** - Switch between 5 providers with one line change
+- **🚀 Production Ready** - Ruby 3.2+, 95%+ test coverage, enterprise patterns
+- **🛡️ Resilient** - Circuit breaker, rate limiter, retry logic with exponential backoff
+- **📈 Observable** - Grafana dashboards, Prometheus metrics, 4 instrumentation backends
+- **🏗️ Rails Ready** - ActiveRecord integration with `has_vector` DSL
+- **🔍 Hybrid Search** - Semantic + keyword search across 4 providers
+- **🧪 Testing** - Built-in mock provider for easy testing
+- **⚡ Performance** - Connection pooling, caching, async batch operations
+
+## 📊 Why Vectra?
+
+| What You Get | Vectra | Others |
+|--------------|--------|--------|
+| **Providers** | 5 unified | 1 each |
+| **Production Patterns** | ✅ 7 built-in | ❌ Manual |
+| **Testing** | ✅ Mock provider | ❌ External DB |
+| **Rails** | ✅ `has_vector` DSL | ⚠️ Manual |
+| **Observability** | ✅ 4 backends | ❌ DIY |
+
+[→ See full comparison](https://vectra-docs.netlify.app)
 
 ## Rails Integration
 
@@ -135,6 +201,33 @@ doc = Document.create!(title: 'Hello', embedding: [0.1, 0.2, ...])
 Document.vector_search(embedding: query_vector, limit: 10)
 ```
 
+### Rails Generator: vectra:index
+
+Generate everything you need for a model with a single command:
+
+```bash
+rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+```
+
+This will:
+
+- **Create a pgvector migration** (only when `provider=pgvector`) adding `embedding` column
+- **Generate a model concern** (`ProductVector`) with `has_vector :embedding`
+- **Update the model** to include `ProductVector`
+- **Append to `config/vectra.yml`** with index metadata (no API keys)
+
+## Production Patterns
+
+Vectra includes 7 production-ready patterns out of the box:
+
+- **Circuit Breaker** - Automatic failover when providers are down
+- **Rate Limiter** - Token bucket algorithm to prevent API throttling
+- **Retry Logic** - Exponential backoff with jitter
+- **Connection Pooling** - Efficient connection management (pgvector)
+- **Caching** - LRU cache with TTL for frequently queried vectors
+- **Health Checks** - `healthy?`, `ping`, and `health_check` methods
+- **Instrumentation** - Datadog, New Relic, Sentry, Honeybadger support
+
 ## Development
 
 ```bash

data/docs/_layouts/default.html

@@ -5,11 +5,106 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta name="description" content="{{ page.description | default: site.description }}">
   <title>{{ page.title }} - {{ site.title }}</title>
+
+  <!-- Primary styles -->
   <link rel="stylesheet" href="{{ site.baseurl }}/assets/style.css">
-  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>◆</text></svg>">
+
+  <!-- Favicon -->
+  <link rel="icon" type="image/svg+xml" href="{{ site.baseurl }}/assets/favicon.svg">
+
+  <!-- SEO Meta -->
+  <meta property="og:title" content="{{ page.title | default: site.title }}">
+  <meta property="og:description" content="{{ page.description | default: site.description }}">
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="{{ page.url | absolute_url }}">
+  <meta property="og:image" content="{{ site.url }}{{ site.baseurl }}/assets/seo.png">
+
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="{{ page.title | default: site.title }}">
+  <meta name="twitter:description" content="{{ page.description | default: site.description }}">
+  <meta name="twitter:image" content="{{ site.url }}{{ site.baseurl }}/assets/seo.png">
+
   <script defer src="https://umami-production-dfb8.up.railway.app/script.js" data-website-id="07e5420c-12d1-4e3c-9dbd-5cecb15a878f"></script>
 </head>
 <body>
-  {{ content }}
+  <!-- Header -->
+  <header class="tma-header">
+    <nav class="tma-nav">
+      <a href="{{ site.baseurl }}/" class="tma-nav__brand">
+        <img src="{{ site.baseurl }}/assets/logo.svg" alt="Vectra" class="tma-nav__logo">
+      </a>
+      <button class="tma-nav__toggle" aria-label="Toggle menu" aria-expanded="false">
+        <span class="tma-nav__toggle-line"></span>
+        <span class="tma-nav__toggle-line"></span>
+        <span class="tma-nav__toggle-line"></span>
+      </button>
+      <ul class="tma-nav__menu" id="nav-menu">
+        <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
+        <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
+        <li><a href="{{ site.baseurl }}/api/overview" class="tma-nav__link">API</a></li>
+        <li><a href="{{ site.baseurl }}/examples" class="tma-nav__link">Examples</a></li>
+        <li><a href="https://github.com/stokry/vectra" target="_blank" class="tma-nav__link tma-nav__link--github">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>
+          GitHub
+        </a></li>
+      </ul>
+    </nav>
+  </header>
+
+  <main style="padding-top: var(--tma-header-height);">
+    {{ content }}
+  </main>
+
+  <!-- Footer -->
+  <footer class="tma-footer">
+    <div class="tma-footer__container">
+      <div>
+        <span class="tma-footer__brand">◆ Vectra</span>
+        <p class="tma-footer__copy">Built with ❤️ for the Ruby community. Mijo Kristo</p>
+      </div>
+      <ul class="tma-footer__links">
+        <li><a href="https://github.com/stokry/vectra">GitHub</a></li>
+        <li><a href="https://rubygems.org/gems/vectra-client">RubyGems</a></li>
+        <li><a href="{{ site.baseurl }}/community/contributing">Contributing</a></li>
+        <li><a href="https://github.com/stokry/vectra/blob/main/LICENSE">MIT License</a></li>
+      </ul>
+    </div>
+  </footer>
+
+  <script>
+    document.addEventListener('DOMContentLoaded', function() {
+      const navToggle = document.querySelector('.tma-nav__toggle');
+      const navMenu = document.querySelector('.tma-nav__menu');
+      
+      if (navToggle && navMenu) {
+        navToggle.addEventListener('click', function(e) {
+          e.preventDefault();
+          e.stopPropagation();
+          const isExpanded = navToggle.getAttribute('aria-expanded') === 'true';
+          navToggle.setAttribute('aria-expanded', !isExpanded);
+          navMenu.classList.toggle('tma-nav__menu--open');
+        });
+        
+        // Close menu when clicking on a link
+        const navLinks = navMenu.querySelectorAll('.tma-nav__link');
+        navLinks.forEach(function(link) {
+          link.addEventListener('click', function() {
+            navToggle.setAttribute('aria-expanded', 'false');
+            navMenu.classList.remove('tma-nav__menu--open');
+          });
+        });
+        
+        // Close menu when clicking outside
+        document.addEventListener('click', function(e) {
+          if (navMenu.classList.contains('tma-nav__menu--open') && 
+              !navMenu.contains(e.target) && 
+              !navToggle.contains(e.target)) {
+            navToggle.setAttribute('aria-expanded', 'false');
+            navMenu.classList.remove('tma-nav__menu--open');
+          }
+        });
+      }
+    });
+  </script>
 </body>
 </html>