vectra-client 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fb1baf885e79af651a89ca695ead6a909a39c495241586ec3a46bdbecfb48ec
-  data.tar.gz: 9e7d3c14ea8108531821790c2d6d9f3d76901f122ab2d78472bf9ac6dbfc32dc
+  metadata.gz: 8a0a1971b5aaa4e71cce684542a9baa8b5c43a47b5e9faa8231bb3dbf5ebe2d1
+  data.tar.gz: d80c394c3cfbc4b94e42e649c26333238feb0e946570e6cb918c13c73d491d37
 SHA512:
-  metadata.gz: b27299838743d313b9416e7c1d54f0bf694853df45526e9e6cdc51f3c2744b2254730100704ca980435ed982baf4d9341ce94a57e9eee8d9da3cc18ceb452fd1
-  data.tar.gz: a4a1ba817e2d094dde020471c63ec954f40de90e5389726b9c486da1aecd7140b80e3f4a0f4a773d654ccb75e3e65dd793bfd655ae749ae2c80a001e9a0259a8
+  metadata.gz: e422697e86cd942b25d49b88a15254789754dea5646fe5407989c4915f4bb4fc3f36a84f19d38a2409bf684c7ce67bde02d012590e909cb980777e35beabf1c1
+  data.tar.gz: 5ef94bacfffe1ce6f67faeaa92febf739b498a14675661612058104dc7d1119e59dc0284a1c32338b08cd73c8cc4aac63e0be249c8250e9d78699dd45eb93b3d

data/.rubocop.yml

@@ -14,9 +14,11 @@ AllCops:
 
 # Layout
 Layout/LineLength:
-  Max: 120
+  Max: 185
   AllowedPatterns:
     - '\A\s*#' # Allow long comment lines
+  Exclude:
+    - 'vectra.gemspec'
 
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
@@ -28,7 +30,7 @@ Metrics/BlockLength:
     - 'vectra.gemspec'
     - 'Rakefile'
     - 'benchmarks/**/*'
-  ExcludedMethods:
+  AllowedMethods:
     - 'included'
     - 'class_methods'
 
@@ -82,10 +84,10 @@ Style/FrozenStringLiteralComment:
   EnforcedStyle: always
 
 Style/SymbolArray:
-  EnforcedStyle: brackets
+  Enabled: false
 
 Style/WordArray:
-  EnforcedStyle: brackets
+  Enabled: false
 
 Style/TrailingCommaInArrayLiteral:
   EnforcedStyleForMultiline: no_comma
@@ -96,6 +98,9 @@ Style/TrailingCommaInHashLiteral:
 Style/TrailingCommaInArguments:
   EnforcedStyleForMultiline: no_comma
 
+Style/MapIntoArray:
+  Enabled: false
+
 # Naming
 Naming/MethodParameterName:
   AllowedNames:
@@ -103,6 +108,13 @@ Naming/MethodParameterName:
     - to
     - db
     - io
+    - n
+
+Naming/PredicatePrefix:
+  Enabled: false # Allow has_vector DSL method
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false # Allow descriptive names
 
 # Lint
 Lint/MissingSuper:
@@ -111,12 +123,15 @@ Lint/MissingSuper:
 Lint/ScriptPermission:
   Enabled: false
 
+Lint/RedundantDirGlobSort:
+  Enabled: false
+
 # RSpec specific
 RSpec/ExampleLength:
-  Max: 15
+  Max: 25
 
 RSpec/MultipleExpectations:
-  Max: 5
+  Max: 10
 
 RSpec/MultipleMemoizedHelpers:
   Max: 10
@@ -125,9 +140,7 @@ RSpec/NestedGroups:
   Max: 5
 
 RSpec/DescribeClass:
-  Enabled: true
-  Exclude:
-    - 'spec/integration/**/*'
+  Enabled: false
 
 RSpec/ContextWording:
   Enabled: false
@@ -144,60 +157,87 @@ RSpec/VerifiedDoubles:
 RSpec/MultipleDescribes:
   Enabled: false
 
-RSpec/DescribeClass:
-  Enabled: false # Allow string descriptions
+RSpec/LeadingSubject:
+  Enabled: false
 
-# Disable problematic Capybara cop
-Capybara/RSpec/PredicateMatcher:
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/DescribedClass:
   Enabled: false
 
 # Gemspec
 Gemspec/DevelopmentDependencies:
   Enabled: false
 
-# Naming
-Naming/MemoizedInstanceVariableName:
-  Enabled: false # Allow descriptive names
+Gemspec/OrderedDependencies:
+  Enabled: false
 
-# Layout
-Layout/LineLength:
-  Max: 185
-  Exclude:
-    - 'vectra.gemspec'
+# Capybara - disable all (causes errors and not needed for this project)
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
 
-# Additional disables for auto-correctable minor issues
-Style/SymbolArray:
+Capybara/CurrentPathExpectation:
   Enabled: false
 
-Style/WordArray:
+Capybara/MatchStyle:
   Enabled: false
 
-Style/MapIntoArray:
+Capybara/NegationMatcher:
   Enabled: false
 
-Lint/RedundantDirGlobSort:
+Capybara/SpecificActions:
   Enabled: false
 
-RSpec/LeadingSubject:
+Capybara/SpecificFinders:
   Enabled: false
 
-RSpec/ExampleLength:
-  Max: 25
+Capybara/SpecificMatcher:
+  Enabled: false
 
-RSpec/MultipleExpectations:
-  Max: 10
+Capybara/VisibilityMatcher:
+  Enabled: false
 
-RSpec/NamedSubject:
+# FactoryBot - not used in this project
+FactoryBot/AttributeDefinedStatically:
   Enabled: false
 
-RSpec/SubjectStub:
+FactoryBot/ConsistentParenthesesStyle:
   Enabled: false
 
-RSpec/DescribedClass:
+FactoryBot/CreateList:
   Enabled: false
 
-Naming/PredicateName:
-  Enabled: false  # Allow has_vector DSL method
+FactoryBot/FactoryClassName:
+  Enabled: false
 
-Gemspec/OrderedDependencies:
+FactoryBot/FactoryNameStyle:
+  Enabled: false
+
+FactoryBot/SyntaxMethods:
+  Enabled: false
+
+# RSpecRails - not used in this project
+RSpecRails/AvoidSetupHook:
+  Enabled: false
+
+RSpecRails/HaveHttpStatus:
+  Enabled: false
+
+RSpecRails/HttpStatus:
+  Enabled: false
+
+RSpecRails/InferredSpecType:
+  Enabled: false
+
+RSpecRails/MinitestAssertions:
+  Enabled: false
+
+RSpecRails/NegationBeValid:
+  Enabled: false
+
+RSpecRails/TravelAround:
   Enabled: false

data/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Proactive Rate Limiting** (`Vectra::RateLimiter`)
+  - Token bucket algorithm for smooth rate limiting
+  - Burst support for handling traffic spikes
+  - Per-provider rate limiter registry
+  - `RateLimitedClient` wrapper for automatic throttling
+  - Prevents API rate limit errors before they occur
+
+- **Structured JSON Logging** (`Vectra::JsonLogger`)
+  - Machine-readable JSON log format
+  - Automatic operation logging via instrumentation
+  - Custom metadata support
+  - Integration with standard Ruby Logger via `JsonFormatter`
+  - Log levels: debug, info, warn, error, fatal
+
+- **Health Check Functionality** (`Vectra::HealthCheck`)
+  - Built-in `client.health_check` method
+  - Connectivity and latency testing
+  - Optional index statistics inclusion
+  - Pool health checking for pgvector
+  - `AggregateHealthCheck` for multi-provider setups
+  - JSON-serializable results
+
+- **Error Tracking Integrations**
+  - Sentry adapter with breadcrumbs, context, and fingerprinting
+  - Honeybadger adapter with severity tags and configurable notifications
+  - Automatic error context and grouping
+
+- **Circuit Breaker Pattern** (`Vectra::CircuitBreaker`)
+  - Three-state circuit (closed, open, half-open)
+  - Automatic failover with fallback support
+  - Per-provider circuit registry
+  - Thread-safe implementation
+  - Configurable failure/success thresholds
+
+## [0.3.0] - 2025-01-08
+
+### Added
+
+- **Async Batch Operations** (`Vectra::Batch`)
+  - Concurrent batch upsert with configurable worker count
+  - Automatic chunking of large vector sets
+  - Async delete and fetch operations
+  - Error aggregation and partial success handling
+
+- **Streaming Results** (`Vectra::Streaming`)
+  - Lazy enumeration for large query result sets
+  - Memory-efficient processing with automatic pagination
+  - `query_each` and `query_stream` methods
+  - Duplicate detection across pages
+
+- **Caching Layer** (`Vectra::Cache` and `Vectra::CachedClient`)
+  - In-memory LRU cache with configurable TTL
+  - Transparent caching for query and fetch operations
+  - Index-level cache invalidation
+  - Thread-safe with mutex synchronization
+
+- **Connection Pool with Warmup** (`Vectra::Pool`)
+  - Configurable pool size and checkout timeout
+  - Connection warmup at startup
+  - Health checking and automatic reconnection
+  - Pool statistics and monitoring
+
+- **CI Benchmark Integration**
+  - Weekly scheduled benchmark runs
+  - PostgreSQL (pgvector) integration in CI
+  - Benchmark result artifact storage
+
+### Configuration
+
+New configuration options:
+- `cache_enabled` - Enable/disable caching (default: false)
+- `cache_ttl` - Cache time-to-live in seconds (default: 300)
+- `cache_max_size` - Maximum cache entries (default: 1000)
+- `async_concurrency` - Concurrent workers for batch ops (default: 4)
+
+### Dependencies
+
+- Added `concurrent-ruby ~> 1.2` for thread-safe operations
+
 ## [0.2.1] - 2025-01-08
 
 ### Added
@@ -109,16 +190,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Planned
 
-### [0.3.0]
+### [0.4.0]
 
 - Weaviate provider implementation
-- Batch operation improvements
-- Performance optimizations
-- Async operations support
+- Additional similarity metrics
+- Vector quantization support
 
 ### [1.0.0]
 
-- Rails integration
-- ActiveRecord-like DSL for vector models
 - Background job integration (Sidekiq, GoodJob)
 - Production-ready with full documentation
+- Performance monitoring dashboard

data/README.md

@@ -1,268 +1,121 @@
-# Vectra 🚀
+# 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)
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
-> **A unified Ruby client for vector databases.** Write once, switch vector database providers seamlessly. Perfect for AI/ML applications, semantic search, and RAG (Retrieval Augmented Generation) systems.
+**A unified Ruby client for vector databases.** Write once, switch providers seamlessly.
 
-## 📖 Complete Documentation
+📖 **Documentation:** [vectra-docs.netlify.app](https://vectra-docs.netlify.app/)
 
-**Full documentation, guides, and API reference available at:** [**https://vectra-docs.netlify.app/**](https://vectra-docs.netlify.app/)
+## Supported Providers
 
-This README provides a quick overview. For detailed guides, examples, and API documentation, visit the official documentation site above.
+| Provider | Type | Status |
+|----------|------|--------|
+| **Pinecone** | Managed Cloud | ✅ Supported |
+| **Qdrant** | Open Source | ✅ Supported |
+| **Weaviate** | Open Source | ✅ Supported |
+| **pgvector** | PostgreSQL | ✅ Supported |
 
----
-
-## ✨ Key Features
-
-- 🔌 **Provider Agnostic** - Switch between vector database providers with minimal code changes
-- 🚀 **Production Ready** - Built for Ruby 3.2+ with comprehensive test coverage (95%+)
-- 🔄 **Resilient** - Built-in retry logic with exponential backoff and circuit breaker patterns
-- 📊 **Rich Results** - Enumerable query results with advanced filtering and mapping capabilities
-- 🛡️ **Type Safe** - Comprehensive input validation and meaningful error messages
-- 📈 **Observable** - Native instrumentation support for Datadog and New Relic
-- 🏗️ **Rails Ready** - Seamless ActiveRecord integration with migrations support
-- 📚 **Well Documented** - Extensive YARD documentation and comprehensive examples
-
-## 🗄️ Supported Vector Databases
-
-| Provider | Type | Status | Docs |
-|----------|------|--------|------|
-| **Pinecone** | Managed Cloud | ✅ Fully Supported | [Guide](https://vectra-docs.netlify.app/providers/pinecone) |
-| **PostgreSQL + pgvector** | SQL Database | ✅ Fully Supported | [Guide](https://vectra-docs.netlify.app/providers/pgvector) |
-| **Qdrant** | Open Source | ✅ Fully Supported | [Guide](https://vectra-docs.netlify.app/providers/qdrant) |
-| **Weaviate** | Open Source | ✅ Fully Supported | [Guide](https://vectra-docs.netlify.app/providers/weaviate) |
-
-
-
-## 📦 Installation
-
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
 gem 'vectra-client'
 ```
 
-Then execute:
-
 ```bash
 bundle install
 ```
 
-Or install directly:
-
-```bash
-gem install vectra-client
-```
-
-### RubyGems Information
-
-- **Gem Name:** `vectra-client`
-- **Latest Version:** 0.2.1
-- **Repository:** [stokry/vectra](https://github.com/stokry/vectra)
-- **RubyGems Page:** [vectra-client](https://rubygems.org/gems/vectra-client)
-- **License:** MIT
-- **Ruby Requirement:** >= 3.2.0
-
-### Provider-Specific Setup
-
-Each vector database may require additional dependencies:
-
-**PostgreSQL + pgvector:**
-```ruby
-gem 'pg', '~> 1.5'
-```
-
-**For Instrumentation:**
-```ruby
-gem 'dogstatsd-ruby'      # Datadog
-gem 'newrelic_rpm'        # New Relic
-```
-
-## 🚀 Quick Start
-
-### 1. Initialize a Client
+## Quick Start
 
 ```ruby
 require 'vectra'
 
-# Pinecone
+# Initialize client (works with any provider)
 client = Vectra::Client.new(
   provider: :pinecone,
   api_key: ENV['PINECONE_API_KEY'],
   environment: 'us-west-4'
 )
 
-# PostgreSQL + pgvector
-client = Vectra::Client.new(
-  provider: :pgvector,
-  database: 'my_app_production',
-  host: 'localhost'
-)
-
-# Qdrant
-client = Vectra::Client.new(
-  provider: :qdrant,
-  host: 'http://localhost:6333'
-)
-```
-
-### 2. Upsert Vectors
-
-```ruby
+# Upsert vectors
 client.upsert(
   vectors: [
-    { 
-      id: 'doc-1', 
-      values: [0.1, 0.2, 0.3], 
-      metadata: { title: 'Introduction to AI' }
-    },
-    { 
-      id: 'doc-2', 
-      values: [0.2, 0.3, 0.4], 
-      metadata: { title: 'Advanced ML Techniques' }
-    }
+    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { title: 'Hello' } },
+    { id: 'doc-2', values: [0.4, 0.5, 0.6], metadata: { title: 'World' } }
   ]
 )
-```
-
-### 3. Search for Similar Vectors
-
-```ruby
-results = client.query(
-  vector: [0.1, 0.2, 0.3],
-  top_k: 5
-)
-
-results.matches.each do |match|
-  puts "#{match['id']}: #{match['score']}"
-  puts "  Metadata: #{match['metadata']}"
-end
-```
 
-### 4. Delete Vectors
+# Search
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+results.each { |match| puts "#{match.id}: #{match.score}" }
 
-```ruby
+# Delete
 client.delete(ids: ['doc-1', 'doc-2'])
 ```
 
-## 📖 Full Documentation
-
-For complete documentation, examples, and guides, visit:
+## Provider Examples
 
-**👉 [https://vectra-docs.netlify.app/](https://vectra-docs.netlify.app/)**
+```ruby
+# Pinecone
+client = Vectra.pinecone(api_key: ENV['PINECONE_API_KEY'], environment: 'us-west-4')
 
-### Documentation Includes:
+# Qdrant (local)
+client = Vectra.qdrant(host: 'http://localhost:6333')
 
-- [Installation Guide](https://vectra-docs.netlify.app/guides/installation)
-- [Getting Started](https://vectra-docs.netlify.app/guides/getting-started)
-- [Provider Guides](https://vectra-docs.netlify.app/providers)
-  - [Pinecone](https://vectra-docs.netlify.app/providers/pinecone)
-  - [PostgreSQL + pgvector](https://vectra-docs.netlify.app/providers/pgvector)
-  - [Qdrant](https://vectra-docs.netlify.app/providers/qdrant)
-  - [Weaviate](https://vectra-docs.netlify.app/providers/weaviate)
-- [API Reference](https://vectra-docs.netlify.app/api/overview)
-- [Code Examples](https://vectra-docs.netlify.app/examples)
-- [Rails Integration Guide](https://vectra-docs.netlify.app/providers/pgvector/)
+# Qdrant (cloud)
+client = Vectra.qdrant(host: 'https://your-cluster.qdrant.io', api_key: ENV['QDRANT_API_KEY'])
 
----
+# Weaviate
+client = Vectra.weaviate(host: 'http://localhost:8080', api_key: ENV['WEAVIATE_API_KEY'])
 
-## 💡 Use Cases
+# pgvector (PostgreSQL)
+client = Vectra.pgvector(connection_url: 'postgres://user:pass@localhost/mydb')
+```
 
-### Semantic Search
-Build intelligent search that understands meaning, not just keywords. Perfect for product discovery, knowledge base search, and content recommendation.
+## Features
 
-### Retrieval Augmented Generation (RAG)
-Combine vector databases with LLMs to enable precise information retrieval for AI applications, chatbots, and knowledge systems.
+- **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
 
-### Duplicate Detection
-Identify and deduplicate similar items across your dataset using vector similarity.
+## Rails Integration
 
-### Recommendation Systems
-Power personalized recommendations based on user behavior and content similarity.
+```ruby
+class Document < ApplicationRecord
+  include Vectra::ActiveRecord
 
----
+  has_vector :embedding,
+    provider: :qdrant,
+    index: 'documents',
+    dimension: 1536
+end
 
+# Auto-indexes on save
+doc = Document.create!(title: 'Hello', embedding: [0.1, 0.2, ...])
 
-## 🛠️ Development
+# Search
+Document.vector_search(embedding: query_vector, limit: 10)
+```
 
-### Set Up Development Environment
+## Development
 
 ```bash
 git clone https://github.com/stokry/vectra.git
 cd vectra
 bundle install
-```
-
-### Run Tests
-
-```bash
-# All tests
 bundle exec rspec
-
-# Unit tests only
-bundle exec rspec spec/vectra
-
-# Integration tests only
-bundle exec rspec spec/integration
-```
-
-### Code Quality
-
-```bash
-# Run RuboCop linter
 bundle exec rubocop
-
-# Generate documentation
-bundle exec rake docs
 ```
 
-## 🤝 Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-See [CHANGELOG.md](CHANGELOG.md) for the complete history of changes.
-
-## 🔗 Links
-
-- **Documentation:** [https://vectra-docs.netlify.app/](https://vectra-docs.netlify.app/)
-- **RubyGems:** [vectra-client](https://rubygems.org/gems/vectra-client)
-- **GitHub:** [stokry/vectra](https://github.com/stokry/vectra)
-- **Issues:** [Report a bug](https://github.com/stokry/vectra/issues)
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-**Built with ❤️ by the Vectra community**
-- 🚧 Performance optimizations
-
-### v1.0.0
-- 🚧 Rails integration
-- 🚧 ActiveRecord-like DSL
-- 🚧 Background job support
-- 🚧 Full documentation
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/stokry/vectra.
-
-1. Fork it
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create a new Pull Request
+Bug reports and pull requests welcome at [github.com/stokry/vectra](https://github.com/stokry/vectra).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Acknowledgments
-
-Inspired by the simplicity of Ruby database gems and the need for a unified vector database interface.
+MIT License - see [LICENSE](LICENSE) file.

data/docs/Gemfile

@@ -6,5 +6,4 @@ gem "jekyll", "~> 4.4"
 gem "jekyll-feed", "~> 0.12"
 gem "jekyll-seo-tag"
 gem "jekyll-sitemap"
-gem "minima", "~> 2.5"
 gem "webrick", "~> 1.8"

data/docs/_config.yml

@@ -1,13 +1,22 @@
 title: Vectra Documentation
-description: Unified Ruby client for vector databases
-theme: minima
+description: A unified Ruby client for vector databases. Build AI-powered search, RAG applications, and recommendation systems.
+url: "https://vectra-docs.netlify.app"
+baseurl: ""
+
 plugins:
   - jekyll-feed
   - jekyll-sitemap
+  - jekyll-seo-tag
 
 markdown: kramdown
 highlighter: rouge
 
+kramdown:
+  syntax_highlighter: rouge
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+
 exclude:
   - Gemfile
   - Gemfile.lock
@@ -16,5 +25,13 @@ exclude:
   - vendor/cache/
   - vendor/gems/
   - vendor/ruby/
+  - _site/
 
 permalink: /:categories/:title/
+
+defaults:
+  - scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: "page"