vectra-client 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20a46681e8f00bb511f72b3ce95d354ff9384bf1344c459f38f125278f6b0e4f
+  data.tar.gz: 789c701852f7ac470407c6bba2a6fcc1c4515f94803591e5054885ed7f60af1e
+SHA512:
+  metadata.gz: 9eb0dcbb37f18fbd0ba6dd75c4707c9e4f78f7eebb7ecc20efadc58a6a14115d73f2edbd1ab89c7fe164442066c40a1c34cff52e330861c76057d4bbf3c81e5e
+  data.tar.gz: 9cd0ffabc9a4da469b713ceda5faa3255648d1e367841fad57b23f4efedda64cb2496248a52889d976e15c855f4bc2e6c35192f6ff0685f3a64591da3340612c

data/.codecov.yml

@@ -0,0 +1,31 @@
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+  status:
+    project:
+      default:
+        target: 90%
+        threshold: 1%
+        if_ci_failed: error
+
+    patch:
+      default:
+        target: 80%
+        threshold: 5%
+        if_ci_failed: error
+
+  ignore:
+    - "spec/**/*"
+    - "lib/vectra/version.rb"
+
+comment:
+  layout: "header, diff, flags, files"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+github_checks:
+  annotations: true

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--color
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,183 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+    - 'node_modules/**/*'
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns:
+    - '\A\s*#' # Allow long comment lines
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Metrics
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'vectra.gemspec'
+    - 'Rakefile'
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 250
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 7
+  CountKeywordArgs: false
+
+# Style
+Style/Documentation:
+  Enabled: false # We use YARD documentation
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false # Allow both single and double quotes
+
+Style/ArgumentsForwarding:
+  Enabled: false # Ruby 3.2+ feature, but not required
+
+Style/IfUnlessModifier:
+  Enabled: false # Allow multi-line if/unless for clarity
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: no_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: no_comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: no_comma
+
+# Naming
+Naming/MethodParameterName:
+  AllowedNames:
+    - id
+    - to
+    - db
+    - io
+
+# Lint
+Lint/MissingSuper:
+  Enabled: false # Allow classes without super calls
+
+# RSpec specific
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/DescribeClass:
+  Enabled: true
+  Exclude:
+    - 'spec/integration/**/*'
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false # Allow both have_received and receive
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false # Allow string descriptions
+
+# Disable problematic Capybara cop
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
+
+# Gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Naming
+Naming/MemoizedInstanceVariableName:
+  Enabled: false # Allow descriptive names
+
+# Layout
+Layout/LineLength:
+  Max: 185
+  Exclude:
+    - 'vectra.gemspec'
+
+# Additional disables for auto-correctable minor issues
+Style/SymbolArray:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Style/MapIntoArray:
+  Enabled: false
+
+Lint/RedundantDirGlobSort:
+  Enabled: false
+
+RSpec/LeadingSubject:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+Gemspec/OrderedDependencies:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2025-01-07
+
+### Added
+
+- **pgvector provider** - Full PostgreSQL with pgvector extension support:
+  - Vector upsert, query, fetch, update, delete operations
+  - Index (table) management with automatic schema creation
+  - Multiple similarity metrics: cosine, euclidean, inner product
+  - Namespace support via namespace column
+  - Metadata filtering with JSONB
+  - IVFFlat index creation for fast similarity search
+- `Vectra.pgvector` convenience method for creating pgvector clients
+- Comprehensive unit and integration tests for pgvector provider
+
+### Changed
+
+- Updated gemspec description to include pgvector
+- Added `pg` gem as development dependency
+
+### Provider Support
+
+- ✅ Pinecone - Fully implemented
+- ✅ pgvector (PostgreSQL) - Fully implemented
+- 🚧 Qdrant - Stub implementation (planned for v0.2.0)
+- 🚧 Weaviate - Stub implementation (planned for v0.3.0)
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+
+- Initial release
+- Pinecone provider with full support for:
+  - Vector upsert, query, fetch, update, delete operations
+  - Index management (list, describe, create, delete)
+  - Namespace support
+  - Metadata filtering
+- Configuration system with global and per-client options
+- Automatic retry logic with exponential backoff
+- Comprehensive error handling with specific error classes:
+  - `AuthenticationError` - API key issues
+  - `RateLimitError` - Rate limiting with retry-after
+  - `NotFoundError` - Resource not found
+  - `ValidationError` - Invalid request parameters
+  - `ServerError` - Server-side errors
+  - `ConnectionError` - Network issues
+  - `TimeoutError` - Request timeouts
+- `Vector` class for vector representation with:
+  - Cosine similarity calculation
+  - Euclidean distance calculation
+  - Metadata support
+- `QueryResult` class with Enumerable support:
+  - Score filtering
+  - Easy iteration
+  - Result statistics
+- Full RSpec test suite
+- YARD documentation
+
+## Planned
+
+### [0.2.0]
+
+- Qdrant provider implementation
+- Enhanced error messages
+- Connection pooling
+- Improved retry strategies
+
+### [0.3.0]
+
+- Weaviate provider implementation
+- Batch operation improvements
+- Performance optimizations
+- Async operations support
+
+### [1.0.0]
+
+- Rails integration
+- ActiveRecord-like DSL for vector models
+- Background job integration (Sidekiq, GoodJob)
+- Production-ready with full documentation

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,127 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team responsible for enforcement at mijo@mijokristo.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All project maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Project maintainers will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from project maintainers, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

data/CONTRIBUTING.md

@@ -0,0 +1,239 @@
+# Contributing to Vectra
+
+Thank you for considering contributing to Vectra! This document outlines the process for contributing to this project.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:
+
+- **Clear title and description**
+- **Steps to reproduce** the problem
+- **Expected behavior** vs **actual behavior**
+- **Ruby version** and **Vectra version**
+- **Provider** you're using (Pinecone, Qdrant, Weaviate)
+- **Code samples** if applicable
+
+### Suggesting Enhancements
+
+Enhancement suggestions are welcome! Please include:
+
+- **Clear use case** for the enhancement
+- **Expected behavior** of the new feature
+- **Examples** of how it would be used
+- **Benefits** to users
+
+### Pull Requests
+
+1. **Fork the repository** and create your branch from `main`:
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Set up your development environment**:
+   ```bash
+   bundle install
+   ```
+
+3. **Make your changes**:
+   - Follow the existing code style
+   - Add tests for any new functionality
+   - Update documentation as needed
+   - Ensure all tests pass
+
+4. **Run the test suite**:
+   ```bash
+   # Run all tests
+   bundle exec rspec
+
+   # Run specific test file
+   bundle exec rspec spec/vectra/client_spec.rb
+
+   # Run with coverage
+   COVERAGE=true bundle exec rspec
+   ```
+
+5. **Run the linter**:
+   ```bash
+   bundle exec rubocop
+
+   # Auto-fix issues
+   bundle exec rubocop -a
+   ```
+
+6. **Commit your changes**:
+   - Use clear, descriptive commit messages
+   - Reference issue numbers when applicable
+   ```bash
+   git commit -m "Add feature X to improve Y (#123)"
+   ```
+
+7. **Push to your fork** and submit a pull request:
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.2 or higher
+- Bundler 2.0+
+
+### Installation
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR-USERNAME/vectra.git
+cd vectra
+
+# Install dependencies
+bundle install
+
+# Run tests to verify setup
+bundle exec rspec
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake
+
+# Run only unit tests
+bundle exec rake spec:unit
+
+# Run only integration tests
+bundle exec rake spec:integration
+
+# Run with coverage report
+COVERAGE=true bundle exec rspec
+```
+
+### Code Style
+
+We use RuboCop to enforce consistent code style. Configuration is in `.rubocop.yml`.
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix violations
+bundle exec rubocop -a
+```
+
+### Documentation
+
+We use YARD for documentation. All public methods should be documented.
+
+```bash
+# Generate documentation
+bundle exec rake docs
+
+# View documentation locally
+open doc/index.html
+```
+
+## Adding a New Provider
+
+To add support for a new vector database provider:
+
+1. **Create provider class** in `lib/vectra/providers/`:
+   ```ruby
+   # lib/vectra/providers/new_provider.rb
+   module Vectra
+     module Providers
+       class NewProvider < Base
+         def provider_name
+           :new_provider
+         end
+
+         # Implement required methods from Base
+       end
+     end
+   end
+   ```
+
+2. **Add to configuration**:
+   Update `SUPPORTED_PROVIDERS` in `lib/vectra/configuration.rb`
+
+3. **Require in main file**:
+   Add to `lib/vectra.rb`
+
+4. **Write comprehensive tests**:
+   - Unit tests in `spec/vectra/providers/new_provider_spec.rb`
+   - Integration tests in `spec/integration/new_provider_integration_spec.rb`
+
+5. **Update documentation**:
+   - Add to README.md
+   - Update CHANGELOG.md
+   - Add YARD documentation
+
+## Testing with VCR
+
+Integration tests use VCR to record HTTP interactions:
+
+```ruby
+# spec/integration/provider_spec.rb
+RSpec.describe "Provider Integration", :vcr do
+  it "performs operation", vcr: { cassette_name: "provider/operation" } do
+    # Test code
+  end
+end
+```
+
+To record new cassettes:
+```bash
+# Delete old cassettes
+rm -rf spec/fixtures/vcr_cassettes/provider
+
+# Run tests with real API (set API keys in ENV)
+PINECONE_API_KEY=your_key bundle exec rspec spec/integration/
+```
+
+## Commit Message Guidelines
+
+We follow conventional commits:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `test:` Adding or updating tests
+- `refactor:` Code refactoring
+- `style:` Code style changes
+- `chore:` Maintenance tasks
+
+Examples:
+```
+feat: add support for Qdrant vector database
+fix: handle rate limit errors correctly
+docs: update README with new examples
+test: add integration tests for Pinecone
+```
+
+## Release Process
+
+Releases are managed by maintainers:
+
+1. Update version in `lib/vectra/version.rb`
+2. Update CHANGELOG.md
+3. Create git tag: `git tag -a v0.2.0 -m "Release v0.2.0"`
+4. Push tag: `git push origin v0.2.0`
+5. Build gem: `gem build vectra.gemspec`
+6. Push to RubyGems: `gem push vectra-0.2.0.gem`
+
+## Questions?
+
+Feel free to open an issue for:
+- Questions about the codebase
+- Clarification on contribution process
+- Feature discussions
+
+## License
+
+By contributing to Vectra, you agree that your contributions will be licensed under the MIT License.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vectra Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.