vectra-client 0.2.1 → 0.2.2

data/docs/assets/style.css

@@ -0,0 +1,295 @@
+/* Main Styles */
+:root {
+  --primary-color: #2d3748;
+  --accent-color: #4299e1;
+  --accent-dark: #2b6cb0;
+  --bg-color: #f7fafc;
+  --text-color: #2d3748;
+  --border-color: #e2e8f0;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--text-color);
+  background: white;
+}
+
+/* Header & Navigation */
+.site-header {
+  background: white;
+  border-bottom: 1px solid var(--border-color);
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.05);
+}
+
+.site-nav {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 20px;
+}
+
+.nav-container {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 0;
+}
+
+.nav-brand {
+  font-size: 24px;
+  font-weight: 700;
+  color: var(--primary-color);
+  text-decoration: none;
+  letter-spacing: -0.5px;
+}
+
+.nav-menu {
+  display: flex;
+  list-style: none;
+  gap: 2rem;
+  align-items: center;
+}
+
+.nav-link {
+  color: var(--text-color);
+  text-decoration: none;
+  font-weight: 500;
+  transition: color 0.3s ease;
+}
+
+.nav-link:hover {
+  color: var(--accent-color);
+}
+
+/* Main Content */
+.site-main {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 3rem 20px;
+}
+
+.home-main {
+  padding: 4rem 20px;
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin: 2rem 0 1rem;
+  color: var(--primary-color);
+  line-height: 1.2;
+}
+
+h2 {
+  font-size: 1.8rem;
+  margin: 2rem 0 1rem;
+  color: var(--primary-color);
+  border-bottom: 2px solid var(--accent-color);
+  padding-bottom: 0.5rem;
+}
+
+h3 {
+  font-size: 1.3rem;
+  margin: 1.5rem 0 0.5rem;
+  color: var(--primary-color);
+}
+
+p {
+  margin: 1rem 0;
+  line-height: 1.8;
+}
+
+a {
+  color: var(--accent-color);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+/* Code Blocks */
+code {
+  background: var(--bg-color);
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: 'Courier New', Courier, monospace;
+  font-size: 0.9em;
+  color: #d73a49;
+}
+
+pre {
+  background: #282c34;
+  color: #abb2bf;
+  padding: 1.5rem;
+  border-radius: 6px;
+  overflow-x: auto;
+  margin: 1.5rem 0;
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+pre code {
+  background: none;
+  color: inherit;
+  padding: 0;
+}
+
+/* Features Grid */
+.features {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  gap: 2rem;
+  margin: 3rem 0;
+}
+
+.feature-card {
+  padding: 2rem;
+  background: var(--bg-color);
+  border-radius: 6px;
+  border-left: 4px solid var(--accent-color);
+}
+
+.feature-card h3 {
+  margin-top: 0;
+  color: var(--accent-color);
+}
+
+/* Quick Links */
+.quick-links {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 1rem;
+  margin: 2rem 0;
+}
+
+.quick-link {
+  padding: 1rem;
+  background: var(--bg-color);
+  border-radius: 4px;
+  text-align: center;
+  border: 1px solid var(--border-color);
+  transition: all 0.3s ease;
+}
+
+.quick-link:hover {
+  border-color: var(--accent-color);
+  box-shadow: 0 2px 8px rgba(66, 153, 225, 0.1);
+}
+
+.quick-link a {
+  display: block;
+  font-weight: 600;
+  color: var(--accent-color);
+}
+
+/* Tables */
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+}
+
+thead {
+  background: var(--bg-color);
+  border-bottom: 2px solid var(--border-color);
+}
+
+th, td {
+  padding: 0.75rem;
+  text-align: left;
+  border-bottom: 1px solid var(--border-color);
+}
+
+th {
+  font-weight: 600;
+  color: var(--primary-color);
+}
+
+/* Lists */
+ul, ol {
+  margin: 1rem 0 1rem 2rem;
+}
+
+li {
+  margin: 0.5rem 0;
+}
+
+/* Footer */
+.site-footer {
+  background: var(--primary-color);
+  color: white;
+  padding: 3rem 20px;
+  margin-top: 4rem;
+  border-top: 1px solid var(--border-color);
+}
+
+.footer-content {
+  max-width: 1200px;
+  margin: 0 auto;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.footer-links {
+  list-style: none;
+  display: flex;
+  gap: 2rem;
+}
+
+.footer-links a {
+  color: #cbd5e0;
+  text-decoration: none;
+  transition: color 0.3s ease;
+}
+
+.footer-links a:hover {
+  color: white;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .nav-container {
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  .nav-menu {
+    flex-direction: column;
+    gap: 0.5rem;
+    text-align: center;
+  }
+
+  h1 {
+    font-size: 2rem;
+  }
+
+  h2 {
+    font-size: 1.5rem;
+  }
+
+  .site-main {
+    padding: 2rem 15px;
+  }
+
+  .footer-content {
+    flex-direction: column;
+    gap: 2rem;
+  }
+
+  .footer-links {
+    flex-direction: column;
+    gap: 1rem;
+    text-align: center;
+  }
+}

data/docs/community/contributing.md

@@ -0,0 +1,89 @@
+---
+layout: page
+title: Contributing
+permalink: /community/contributing/
+---
+
+# Contributing to Vectra
+
+We welcome contributions! Here's how to get started.
+
+## Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/stokry/vectra.git
+cd vectra
+```
+
+2. Install dependencies:
+```bash
+bundle install
+```
+
+3. Run tests:
+```bash
+bundle exec rspec
+```
+
+## Making Changes
+
+1. Create a feature branch:
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Make your changes and write tests
+3. Run linter:
+```bash
+bundle exec rubocop
+```
+
+4. Commit and push:
+```bash
+git add .
+git commit -m "Description of changes"
+git push origin feature/your-feature-name
+```
+
+5. Create a Pull Request
+
+## Code Style
+
+We use RuboCop for code style. Ensure your code passes:
+
+```bash
+bundle exec rubocop
+```
+
+## Testing
+
+All changes require tests:
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific suite
+bundle exec rspec spec/vectra
+
+# Run with coverage
+bundle exec rspec --cov
+```
+
+## Documentation
+
+Please update documentation for any changes:
+
+- Update README.md for user-facing changes
+- Update CHANGELOG.md
+- Add examples if needed
+
+## Questions?
+
+Feel free to:
+- Open an issue on GitHub
+- Check existing issues and discussions
+- Read the [Implementation Guide](https://github.com/stokry/vectra/blob/main/IMPLEMENTATION_GUIDE.md)
+
+Thank you for contributing! 🙌

data/docs/examples/basic-usage.md

@@ -0,0 +1,102 @@
+---
+layout: page
+title: Basic Usage
+permalink: /examples/basic-usage/
+---
+
+# Basic Usage Examples
+
+## Simple Search
+
+```ruby
+require 'vectra'
+
+client = Vectra::Client.new(
+  provider: :pinecone,
+  api_key: ENV['PINECONE_API_KEY'],
+  environment: 'us-west-4'
+)
+
+# Search for similar vectors
+results = client.query(
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5
+)
+
+puts results.matches.count
+```
+
+## Batch Operations
+
+```ruby
+# Upsert multiple vectors at once
+vectors = [
+  { id: '1', values: [0.1, 0.2, 0.3], metadata: { title: 'Doc 1' } },
+  { id: '2', values: [0.2, 0.3, 0.4], metadata: { title: 'Doc 2' } },
+  { id: '3', values: [0.3, 0.4, 0.5], metadata: { title: 'Doc 3' } }
+]
+
+client.upsert(vectors: vectors)
+
+# Delete multiple vectors
+client.delete(ids: ['1', '2', '3'])
+```
+
+## Rails Integration
+
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.database = Rails.configuration.database_configuration[Rails.env]['database']
+end
+
+# app/models/document.rb
+class Document < ApplicationRecord
+  include Vectra::ActiveRecord
+  
+  vector_search :embedding
+  
+  def generate_embedding
+    # Generate embedding using OpenAI, Cohere, etc.
+    embedding_vector = generate_vector_from_text(content)
+    self.embedding = embedding_vector
+  end
+end
+
+# Usage
+doc = Document.find(1)
+similar_docs = doc.vector_search(limit: 10)
+```
+
+## With Metadata Filtering
+
+```ruby
+results = client.query(
+  vector: [0.1, 0.2, 0.3],
+  top_k: 10,
+  include_metadata: true
+)
+
+results.matches.each do |match|
+  puts "ID: #{match['id']}"
+  puts "Score: #{match['score']}"
+  puts "Metadata: #{match['metadata']}"
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.query(vector: [0.1, 0.2, 0.3])
+rescue Vectra::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+rescue Vectra::ValidationError => e
+  puts "Invalid input: #{e.message}"
+rescue => e
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+See [Getting Started]({{ site.baseurl }}/guides/getting-started) for more examples.

data/docs/examples/index.md

@@ -0,0 +1,32 @@
+---
+layout: page
+title: Examples
+permalink: /examples/
+---
+
+# Code Examples
+
+Explore practical examples to get started with Vectra:
+
+## Basic Examples
+
+- [Basic Usage]({{ site.baseurl }}/examples/basic-usage/) - Simple searches and operations
+- [Batch Operations]({{ site.baseurl }}/examples/basic-usage/#batch-operations) - Working with multiple vectors
+- [Error Handling]({{ site.baseurl }}/examples/basic-usage/#error-handling) - Proper error handling patterns
+
+## Provider-Specific Examples
+
+- [Pinecone Example]({{ site.baseurl }}/providers/pinecone/#example)
+- [Qdrant Example]({{ site.baseurl }}/providers/qdrant/#example)
+- [Weaviate Example]({{ site.baseurl }}/providers/weaviate/#example)
+- [pgvector Example]({{ site.baseurl }}/providers/pgvector/#example)
+
+## Rails Integration
+
+Check out the [pgvector guide]({{ site.baseurl }}/providers/pgvector/) for Rails ActiveRecord integration examples.
+
+## Need More Examples?
+
+- Check the [GitHub Repository](https://github.com/stokry/vectra/tree/main/examples)
+- See the [Implementation Guide](https://github.com/stokry/vectra/blob/main/IMPLEMENTATION_GUIDE.md)
+- Review [Integration Tests](https://github.com/stokry/vectra/tree/main/spec/integration)

data/docs/guides/getting-started.md

@@ -0,0 +1,90 @@
+---
+layout: page
+title: Getting Started
+permalink: /guides/getting-started/
+---
+
+# Getting Started with Vectra
+
+## Initialize a Client
+
+```ruby
+require 'vectra'
+
+# Initialize with Pinecone
+client = Vectra::Client.new(
+  provider: :pinecone,
+  api_key: ENV['PINECONE_API_KEY'],
+  environment: 'us-west-4'
+)
+```
+
+## Basic Operations
+
+### Upsert Vectors
+
+```ruby
+client.upsert(
+  vectors: [
+    {
+      id: 'vec-1',
+      values: [0.1, 0.2, 0.3],
+      metadata: { title: 'Document 1' }
+    },
+    {
+      id: 'vec-2',
+      values: [0.2, 0.3, 0.4],
+      metadata: { title: 'Document 2' }
+    }
+  ]
+)
+```
+
+### Query (Search)
+
+```ruby
+results = client.query(
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5,
+  include_metadata: true
+)
+
+results.matches.each do |match|
+  puts "ID: #{match['id']}, Score: #{match['score']}"
+end
+```
+
+### Delete Vectors
+
+```ruby
+client.delete(ids: ['vec-1', 'vec-2'])
+```
+
+### Get Vector Stats
+
+```ruby
+stats = client.stats
+puts "Index dimension: #{stats['dimension']}"
+puts "Vector count: #{stats['vector_count']}"
+```
+
+## Configuration
+
+Create a configuration file (Rails: `config/initializers/vectra.rb`):
+
+```ruby
+Vectra.configure do |config|
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']
+  config.environment = 'us-west-4'
+end
+
+# Later in your code:
+client = Vectra::Client.new
+```
+
+## Next Steps
+
+- [API Reference]({{ site.baseurl }}/api/overview)
+- [Provider Guides]({{ site.baseurl }}/providers)
+- [Examples]({{ site.baseurl }}/examples/basic-usage)

data/docs/guides/installation.md

@@ -0,0 +1,67 @@
+---
+layout: page
+title: Installation
+permalink: /guides/installation/
+---
+
+# Installation Guide
+
+## Requirements
+
+- Ruby 3.2.0 or higher
+- Bundler
+
+## Install via Bundler
+
+Add Vectra to your Gemfile:
+
+```ruby
+gem 'vectra-client'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Install Standalone
+
+Alternatively, install via RubyGems:
+
+```bash
+gem install vectra-client
+```
+
+## Rails Integration
+
+For Rails applications, run the install generator:
+
+```bash
+rails generate vectra:install
+```
+
+This will create an initializer file at `config/initializers/vectra.rb`.
+
+## Provider-Specific Setup
+
+Each vector database provider may require additional dependencies:
+
+### PostgreSQL with pgvector
+```ruby
+gem 'pg', '~> 1.5'
+```
+
+### Instrumentation
+
+#### Datadog
+```ruby
+gem 'dogstatsd-ruby'
+```
+
+#### New Relic
+```ruby
+gem 'newrelic_rpm'
+```
+
+See [Provider Guides]({{ site.baseurl }}/providers) for detailed setup instructions.

data/docs/index.md

@@ -0,0 +1,53 @@
+---
+layout: home
+title: Vectra
+---
+
+# Welcome to Vectra Documentation
+
+**Vectra** is a unified Ruby client for vector databases that allows you to write once and switch providers easily.
+
+## Supported Vector Databases
+
+- **Pinecone** - Managed vector database in the cloud
+- **Qdrant** - Open-source vector database
+- **Weaviate** - Open-source vector search engine
+- **PostgreSQL with pgvector** - SQL database with vector support
+
+## Quick Links
+
+- [Installation Guide]({{ site.baseurl }}/guides/installation)
+- [Getting Started]({{ site.baseurl }}/guides/getting-started)
+- [API Reference]({{ site.baseurl }}/api/overview)
+- [Examples]({{ site.baseurl }}/examples/basic-usage)
+- [Contributing]({{ site.baseurl }}/community/contributing)
+
+## Key Features
+
+- 🔄 **Provider Agnostic** - Switch between different vector database providers with minimal code changes
+- 🚀 **Easy Integration** - Works seamlessly with Rails and other Ruby frameworks
+- 📊 **Vector Operations** - Create, search, update, and delete vectors
+- 🔌 **Multiple Providers** - Support for leading vector database platforms
+- 📈 **Instrumentation** - Built-in support for Datadog and New Relic monitoring
+- 🗄️ **ActiveRecord Integration** - Native support for Rails models
+
+## Get Started
+
+```ruby
+require 'vectra'
+
+# Initialize client
+client = Vectra::Client.new(provider: :pinecone, api_key: 'your-key')
+
+# Upsert vectors
+client.upsert(
+  vectors: [
+    { id: '1', values: [0.1, 0.2, 0.3], metadata: { text: 'example' } }
+  ]
+)
+
+# Search
+results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+```
+
+For more detailed examples, see [Basic Usage]({{ site.baseurl }}/examples/basic-usage).