vectra-client 0.2.0 → 0.2.2

data/docs/providers/index.md

@@ -0,0 +1,62 @@
+---
+layout: page
+title: Providers
+permalink: /providers/
+---
+
+# Vector Database Providers
+
+Vectra supports multiple vector database providers. Choose the one that best fits your needs:
+
+## Supported Providers
+
+| Provider | Type | Best For | Documentation |
+|----------|------|----------|---|
+| **Pinecone** | Managed Cloud | Production, Fully managed | [Guide]({{ site.baseurl }}/providers/pinecone) |
+| **Qdrant** | Open Source | Self-hosted, High performance | [Guide]({{ site.baseurl }}/providers/qdrant) |
+| **Weaviate** | Open Source | Semantic search, GraphQL | [Guide]({{ site.baseurl }}/providers/weaviate) |
+| **PostgreSQL + pgvector** | SQL Database | SQL integration, ACID | [Guide]({{ site.baseurl }}/providers/pgvector) |
+
+## Quick Comparison
+
+### Pinecone
+- ✅ Fully managed service
+- ✅ Easy setup
+- ✅ Scalable
+- ❌ Cloud only
+- ❌ Paid service
+
+### Qdrant
+- ✅ Open source
+- ✅ Self-hosted
+- ✅ High performance
+- ✅ Multiple deployment options
+- ❌ More configuration needed
+
+### Weaviate
+- ✅ Open source
+- ✅ Semantic search
+- ✅ GraphQL API
+- ✅ Multi-model support
+- ❌ More complex
+
+### PostgreSQL + pgvector
+- ✅ SQL database
+- ✅ ACID transactions
+- ✅ Existing infrastructure
+- ✅ Affordable
+- ❌ Not specialized for vectors
+
+## Switching Providers
+
+One of Vectra's key features is easy provider switching:
+
+```ruby
+# All it takes is changing one line!
+client = Vectra::Client.new(provider: :qdrant)
+
+# All your code remains the same
+results = client.query(vector: [0.1, 0.2, 0.3])
+```
+
+See the [Getting Started Guide]({{ site.baseurl }}/guides/getting-started) for more information.

data/docs/providers/pgvector.md

@@ -0,0 +1,95 @@
+---
+layout: page
+title: PostgreSQL with pgvector
+permalink: /providers/pgvector/
+---
+
+# PostgreSQL with pgvector Provider
+
+[pgvector](https://github.com/pgvector/pgvector) is a PostgreSQL extension for vector data.
+
+## Setup
+
+### Prerequisites
+
+```bash
+# Install PostgreSQL with pgvector extension
+# macOS with Homebrew
+brew install postgresql
+
+# Enable pgvector extension
+psql -d your_database -c "CREATE EXTENSION IF NOT EXISTS vector;"
+```
+
+### Connect with Vectra
+
+```ruby
+client = Vectra::Client.new(
+  provider: :pgvector,
+  database: 'my_database',
+  host: 'localhost',
+  port: 5432,
+  user: 'postgres',
+  password: ENV['DB_PASSWORD']
+)
+```
+
+## Features
+
+- ✅ Upsert vectors
+- ✅ Query/search
+- ✅ Delete vectors
+- ✅ SQL integration
+- ✅ ACID transactions
+- ✅ Complex queries
+- ✅ Rails ActiveRecord integration
+
+## Example
+
+```ruby
+# Initialize client
+client = Vectra::Client.new(
+  provider: :pgvector,
+  database: 'vectors_db',
+  host: 'localhost'
+)
+
+# Upsert vectors
+client.upsert(
+  vectors: [
+    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { title: 'Doc 1' } }
+  ]
+)
+
+# Search using cosine distance
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+```
+
+## ActiveRecord Integration
+
+```ruby
+class Document < ApplicationRecord
+  include Vectra::ActiveRecord
+  
+  vector_search :embedding_vector
+end
+
+# Search
+docs = Document.vector_search([0.1, 0.2, 0.3], limit: 10)
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `database` | String | Yes | Database name |
+| `host` | String | Yes | PostgreSQL host |
+| `port` | Integer | No | PostgreSQL port (default: 5432) |
+| `user` | String | No | Database user |
+| `password` | String | No | Database password |
+| `schema` | String | No | Database schema |
+
+## Documentation
+
+- [pgvector GitHub](https://github.com/pgvector/pgvector)
+- [pgvector Docs](https://github.com/pgvector/pgvector#readme)

data/docs/providers/pinecone.md

@@ -0,0 +1,72 @@
+---
+layout: page
+title: Pinecone
+permalink: /providers/pinecone/
+---
+
+# Pinecone Provider
+
+[Pinecone](https://www.pinecone.io/) is a managed vector database in the cloud.
+
+## Setup
+
+1. Create a Pinecone account at https://www.pinecone.io/
+2. Create an index and get your API key
+3. Set up Vectra:
+
+```ruby
+client = Vectra::Client.new(
+  provider: :pinecone,
+  api_key: ENV['PINECONE_API_KEY'],
+  index_name: 'my-index',
+  environment: 'us-west-4'
+)
+```
+
+## Features
+
+- ✅ Upsert vectors
+- ✅ Query/search
+- ✅ Delete vectors
+- ✅ Fetch vectors by ID
+- ✅ Index statistics
+- ✅ Metadata filtering
+- ✅ Namespace support
+
+## Example
+
+```ruby
+# Initialize client
+client = Vectra::Client.new(
+  provider: :pinecone,
+  api_key: ENV['PINECONE_API_KEY'],
+  environment: 'us-west-4'
+)
+
+# Upsert vectors
+client.upsert(
+  vectors: [
+    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { title: 'Page 1' } },
+    { id: 'doc-2', values: [0.2, 0.3, 0.4], metadata: { title: 'Page 2' } }
+  ]
+)
+
+# Search
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+results.matches.each do |match|
+  puts "#{match['id']}: #{match['score']}"
+end
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `api_key` | String | Yes | Your Pinecone API key |
+| `environment` | String | Yes | Pinecone environment (e.g., 'us-west-4') |
+| `index_name` | String | No | Index name (if not set globally) |
+
+## Documentation
+
+- [Pinecone Docs](https://docs.pinecone.io/)
+- [Pinecone API Reference](https://docs.pinecone.io/reference/api/)

data/docs/providers/qdrant.md

@@ -0,0 +1,73 @@
+---
+layout: page
+title: Qdrant
+permalink: /providers/qdrant/
+---
+
+# Qdrant Provider
+
+[Qdrant](https://qdrant.tech/) is an open-source vector search engine.
+
+## Setup
+
+### Local Installation
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+### Connect with Vectra
+
+```ruby
+client = Vectra::Client.new(
+  provider: :qdrant,
+  host: 'localhost',
+  port: 6333,
+  collection_name: 'my-collection'
+)
+```
+
+## Features
+
+- ✅ Upsert vectors
+- ✅ Query/search
+- ✅ Delete vectors
+- ✅ Fetch vectors by ID
+- ✅ Collection management
+- ✅ Metadata filtering
+- ✅ Hybrid search
+
+## Example
+
+```ruby
+# Initialize client
+client = Vectra::Client.new(
+  provider: :qdrant,
+  host: 'localhost',
+  port: 6333
+)
+
+# Upsert vectors
+client.upsert(
+  vectors: [
+    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { source: 'web' } }
+  ]
+)
+
+# Search
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 10)
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `host` | String | Yes | Qdrant host address |
+| `port` | Integer | Yes | Qdrant port (default: 6333) |
+| `collection_name` | String | No | Collection name |
+| `api_key` | String | No | API key if auth is enabled |
+
+## Documentation
+
+- [Qdrant Docs](https://qdrant.tech/documentation/)
+- [Qdrant API Reference](https://api.qdrant.tech/)

data/docs/providers/weaviate.md

@@ -0,0 +1,72 @@
+---
+layout: page
+title: Weaviate
+permalink: /providers/weaviate/
+---
+
+# Weaviate Provider
+
+[Weaviate](https://weaviate.io/) is an open-source vector search engine with semantic search capabilities.
+
+## Setup
+
+### Local Installation
+
+```bash
+docker run -p 8080:8080 semitechnologies/weaviate:latest
+```
+
+### Connect with Vectra
+
+```ruby
+client = Vectra::Client.new(
+  provider: :weaviate,
+  host: 'localhost',
+  port: 8080,
+  class_name: 'Document'
+)
+```
+
+## Features
+
+- ✅ Upsert vectors
+- ✅ Query/search
+- ✅ Delete vectors
+- ✅ Class management
+- ✅ Metadata filtering
+- ✅ Semantic search
+
+## Example
+
+```ruby
+# Initialize client
+client = Vectra::Client.new(
+  provider: :weaviate,
+  host: 'localhost',
+  port: 8080
+)
+
+# Upsert vectors
+client.upsert(
+  vectors: [
+    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { category: 'news' } }
+  ]
+)
+
+# Search
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `host` | String | Yes | Weaviate host address |
+| `port` | Integer | Yes | Weaviate port (default: 8080) |
+| `class_name` | String | No | Class name for vectors |
+| `api_key` | String | No | API key if auth is enabled |
+
+## Documentation
+
+- [Weaviate Docs](https://weaviate.io/developers)
+- [Weaviate API Reference](https://weaviate.io/developers/weaviate/api/rest)

data/lib/vectra/configuration.rb

@@ -56,7 +56,11 @@ module Vectra
     # @raise [ConfigurationError] if configuration is invalid
     def validate!
       raise ConfigurationError, "Provider must be configured" if provider.nil?
-      raise ConfigurationError, "API key must be configured" if api_key.nil? || api_key.empty?
+
+      # API key is optional for some providers (Qdrant local, pgvector)
+      if !api_key_optional_provider? && (api_key.nil? || api_key.empty?)
+        raise ConfigurationError, "API key must be configured"
+      end
 
       validate_provider_specific!
     end
@@ -106,6 +110,11 @@ module Vectra
 
     private
 
+    # Providers that don't require API key (local instances)
+    def api_key_optional_provider?
+      %i[qdrant pgvector].include?(provider)
+    end
+
     def validate_provider_specific!
       case provider
       when :pinecone

data/lib/vectra/providers/base.rb

@@ -218,6 +218,16 @@ module Vectra
         end
       end
 
+      # Handle Faraday::RetriableResponse from retry middleware
+      # This is raised when all retries are exhausted
+      #
+      # @param exception [Faraday::RetriableResponse] the exception
+      # @raise [Error] appropriate error for the response
+      def handle_retriable_response(exception)
+        response = exception.response
+        handle_error(response)
+      end
+
       # Extract error message from response body
       #
       # @param body [Hash, String, nil] response body