Migrate to Container-Based Testing and Add Host-Based Index Targeting

[ScotterC]

This PR modernizes the Pinecone Ruby gem's testing infrastructure by migrating from VCR-based testing to local Pinecone containers and introduces host-based index targeting for improved performance.

🚀 Key Features

Host-Based Index Targeting (v1.2)

• New recommended approach: Direct host targeting eliminates extra API calls
• Performance improvement: No more describe_index calls for every vector operation
• Backward compatibility: Legacy name-based access still supported with deprecation warnings

New recommended approach (faster)

client = Pinecone::Client.new
index = client.index(host: "my-index-abc123.svc.us-east1.pinecone.io")

Legacy approach (still works, but slower)

index = client.index("my-index-name") # Makes extra API call

Container-Based Testing Infrastructure

• Local development: Docker containers for all Pinecone operations
• CI/CD integration: GitHub Actions runs against local containers
• No external dependencies: Tests run without API keys or network calls
• Enhanced validation: Tests verify actual data content, not just HTTP status codes

🔧 Technical Changes

API Enhancements

• Added host parameter to Pinecone::Client#index()
• Added global host configuration: Pinecone.configure { |c| c.host = "..." }
• HTTP/HTTPS protocol detection (HTTP for localhost, HTTPS for production)
• Improved error handling and validation

Test Infrastructure Overhaul

• Removed VCR dependencies across all specs
• Container-based testing for vector operations (dense: 5081, sparse: 5082, database: 5080)
• Strategic mocking for control plane operations (collections)
• Enhanced validations verify actual data presence, not just key existence

📊 Test Results

Before: Flaky VCR-based tests with external API dependencies
After:

• 123 examples, 0 failures ✅
• 4 pending (3 sparse operations + 1 deprecation test in container env)
• Fast execution: ~5 seconds vs variable network timing
• Reliable: No external API dependencies or rate limits

🐳 Container Architecture

Data Plane (Vector Operations): Local Containers

• Dense vectors: localhost:5081 (2D, cosine similarity)
• Sparse vectors: localhost:5082 (sparse, dotproduct)
• Index management: localhost:5080 (create, delete, describe, configure)

Control Plane (Management): Strategic Mocking

• Collections API (not supported by containers)
• Realistic mock responses matching production API

🔄 Migration Path

Immediate Benefits:

• Existing code continues to work unchanged
• Tests run faster and more reliably
• Local development doesn't require API keys

Recommended Updates:

Before (slower)

index = client.index("my-index-name")

After (faster)

index = client.index(host: "my-index-abc123.svc.us-east1.pinecone.io")

🚦 CI/CD Integration

GitHub Actions now:

• Spins up 3 Pinecone containers automatically
• Waits for container readiness with health checks
• Runs full test suite against local containers
• Tests multiple Ruby versions (3.2, 3.3) consistently

📈 Performance Impact

• Eliminated extra API calls for vector operations
• ~2x faster test execution
• Reduced API rate limit pressure
• More reliable local development

🔒 Backward Compatibility

• All existing code continues to work
• Deprecation warnings guide users to new approach
• Can be silenced with Pinecone.configuration.silence_deprecation_warnings = true

📚 Documentation

• Updated README with v1.2 features and local development setup
• Added Docker Compose instructions
• Enhanced configuration examples
• Clear migration guidance