vectra-client 0.3.3 → 0.4.0

data/docs/guides/monitoring.md

@@ -138,6 +138,56 @@ run YourApp
 
 ## Grafana Dashboard
 
+### Live Dashboard Preview
+
+Vectra includes a comprehensive Grafana dashboard with 11 professional panels for monitoring all aspects of your vector database operations:
+
+<div class="tma-dashboard-showcase">
+  <div class="tma-dashboard-showcase__image">
+    <img src="{{ site.baseurl }}/grafana_final.png" alt="Vectra Grafana Dashboard - Real-time monitoring of vector database operations" class="tma-dashboard-screenshot">
+  </div>
+  <div class="tma-dashboard-showcase__features">
+    <h4>Dashboard Features</h4>
+    <ul>
+      <li><strong>Real-time Metrics:</strong> Request rate, latency, error tracking</li>
+      <li><strong>Performance Monitoring:</strong> P50, P95, P99 latency percentiles</li>
+      <li><strong>Cache Analytics:</strong> Hit ratio and performance metrics</li>
+      <li><strong>Provider Insights:</strong> Multi-provider comparison and distribution</li>
+      <li><strong>Connection Pooling:</strong> pgvector pool status and utilization</li>
+      <li><strong>Visual Analytics:</strong> Time series, pie charts, bar gauges</li>
+    </ul>
+    <div class="tma-dashboard-showcase__actions">
+      <a href="https://github.com/stokry/vectra/tree/main/examples#grafana-dashboard" class="tma-button tma-button--primary" target="_blank" rel="noopener">
+        Get Dashboard JSON →
+      </a>
+      <a href="https://github.com/stokry/vectra/blob/main/examples/GRAFANA_QUICKSTART.md" class="tma-button tma-button--secondary" target="_blank" rel="noopener">
+        Quick Start Guide →
+      </a>
+    </div>
+  </div>
+</div>
+
+### Quick Setup
+
+Get started in 5 minutes:
+
+1. **Start Prometheus Exporter:**
+   ```bash
+   gem install prometheus-client
+   ruby examples/prometheus-exporter.rb
+   ```
+
+2. **Import Dashboard:**
+   - Sign up at [grafana.com](https://grafana.com) (free tier available)
+   - Add Prometheus data source
+   - Import `examples/grafana-dashboard.json`
+
+3. **View Metrics:**
+   - Dashboard populates with real-time data
+   - Perfect for monitoring and screenshots
+
+See the [Quick Start Guide](https://github.com/stokry/vectra/blob/main/examples/GRAFANA_QUICKSTART.md) for detailed setup instructions.
+
 ### Dashboard JSON Template
 
 Save as `vectra-dashboard.json` and import into Grafana:

data/docs/providers/index.md

@@ -16,6 +16,7 @@ Vectra supports multiple vector database providers. Choose the one that best fit
 | [**Qdrant**]({{ site.baseurl }}/providers/qdrant) | Open Source | Self-hosted, Performance |
 | [**Weaviate**]({{ site.baseurl }}/providers/weaviate) | Open Source | Semantic search, GraphQL |
 | [**pgvector**]({{ site.baseurl }}/providers/pgvector) | PostgreSQL | SQL integration, ACID |
+| [**Memory**]({{ site.baseurl }}/providers/memory) | In-Memory | Testing, CI, local dev |
 
 ## Quick Comparison
 
@@ -75,6 +76,17 @@ client.upsert(vectors: [...])
 results = client.query(vector: [...], top_k: 5)
 ```
 
+For **tests and CI** you can use the in-memory provider:
+
+```ruby
+# config/initializers/vectra.rb (test environment)
+Vectra.configure do |config|
+  config.provider = :memory if Rails.env.test?
+end
+
+client = Vectra::Client.new
+```
+
 ## Next Steps
 
 - [Getting Started Guide]({{ site.baseurl }}/guides/getting-started)

data/docs/providers/memory.md

@@ -0,0 +1,145 @@
+---
+layout: page
+title: Memory Provider
+permalink: /providers/memory/
+---
+
+# Memory Provider
+
+The **Memory provider** is an in-memory vector store built into Vectra.
+It is designed **exclusively for testing, local development, and CI** – no external database required.
+
+> Not for production use. All data lives in process memory and is lost when the process exits.
+
+## When to Use
+
+- ✅ RSpec / Minitest suites (fast, isolated tests)
+- ✅ Local development without provisioning Pinecone/Qdrant/Weaviate/pgvector
+- ✅ CI pipelines where external services are not available
+- ❌ Not suitable for production workloads
+
+## Setup
+
+### Global Configuration (Rails Example)
+
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.provider = :memory if Rails.env.test?
+end
+```
+
+Then in your application code:
+
+```ruby
+client = Vectra::Client.new
+```
+
+### Direct Construction
+
+```ruby
+require "vectra"
+
+client = Vectra.memory
+```
+
+No `host`, `api_key`, or environment configuration is required.
+
+## Features
+
+- ✅ `upsert` – store vectors in memory
+- ✅ `query` – cosine similarity search (with optional metadata filtering)
+- ✅ `fetch` – retrieve vectors by ID
+- ✅ `update` – merge metadata for existing vectors
+- ✅ `delete` – delete by IDs, namespace, filter, or `delete_all`
+- ✅ `list_indexes` / `describe_index` – basic index metadata (dimension, metric)
+- ✅ `stats` – vector counts per namespace
+- ✅ `clear!` – wipe all data between tests
+
+## Basic Usage
+
+```ruby
+client = Vectra.memory
+
+# Upsert
+client.upsert(
+  index: "documents",
+  vectors: [
+    {
+      id: "doc-1",
+      values: [0.1, 0.2, 0.3],
+      metadata: { title: "Hello", category: "docs" }
+    }
+  ],
+  namespace: "test-suite"
+)
+
+# Query
+results = client.query(
+  index: "documents",
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5,
+  namespace: "test-suite",
+  filter: { category: "docs" },
+  include_metadata: true
+)
+
+results.each do |match|
+  puts "#{match.id}: #{match.metadata["title"]} (score=#{match.score.round(3)})"
+end
+```
+
+## Metadata Filtering
+
+The Memory provider supports a subset of the same filter operators as other providers:
+
+```ruby
+results = client.query(
+  index: "products",
+  vector: query_embedding,
+  top_k: 10,
+  filter: {
+    status: ["active", "preview"],         # IN
+    price: { "$gte" => 10, "$lte" => 100 },# range
+    brand: { "$ne" => "Acme" }             # not equal
+  },
+  include_metadata: true
+)
+```
+
+Supported operators:
+
+- Equality: `{ field: "value" }` or `{ field: { "$eq" => "value" } }`
+- Inequality: `{ field: { "$ne" => "value" } }`
+- Ranges: `{ field: { "$gt" => 10 } }`, `{ "$gte" => 10 }`, `{ "$lt" => 20 }`, `{ "$lte" => 20 }`
+- Arrays / IN: `{ field: ["a", "b"] }` or `{ field: { "$in" => ["a", "b"] } }`
+
+## Resetting State Between Tests
+
+The Memory provider exposes a `clear!` method to reset all in-memory state:
+
+```ruby
+RSpec.describe "MyService" do
+  let(:client) { Vectra.memory }
+
+  before do
+    client.provider.clear! if client.provider.respond_to?(:clear!)
+  end
+
+  # your tests...
+end
+```
+
+You can also call `clear!` on the provider obtained from a regular `Vectra::Client`:
+
+```ruby
+client = Vectra::Client.new(provider: :memory)
+client.provider.clear!
+```
+
+## Limitations
+
+- Not distributed – data lives only in the current Ruby process.
+- No persistence – all vectors are lost when the process exits or `clear!` is called.
+- Intended for **testing and development only**, not for production traffic.
+

data/docs/providers/weaviate.md

@@ -18,53 +18,112 @@ docker run -p 8080:8080 semitechnologies/weaviate:latest
 
 ### Connect with Vectra
 
+You can either use the convenience constructor:
+
+```ruby
+client = Vectra.weaviate(
+  api_key: ENV["WEAVIATE_API_KEY"], # optional for local / required for cloud
+  host: "http://localhost:8080"     # or your cloud endpoint
+)
+```
+
+or configure via `Vectra::Client`:
+
 ```ruby
 client = Vectra::Client.new(
   provider: :weaviate,
-  host: 'localhost',
-  port: 8080,
-  class_name: 'Document'
+  api_key: ENV["WEAVIATE_API_KEY"],
+  host: "https://your-weaviate-instance"
 )
 ```
 
 ## Features
 
-- ✅ Upsert vectors
-- ✅ Query/search
-- ✅ Delete vectors
-- ✅ Class management
-- ✅ Metadata filtering
-- ✅ Semantic search
+- ✅ Upsert vectors into Weaviate classes (per-index `class`)
+- ✅ Vector similarity search via GraphQL `nearVector`
+- ✅ Fetch by IDs
+- ✅ Metadata filtering (exact match, ranges, arrays)
+- ✅ Namespace support via `_namespace` property
+- ✅ Delete by IDs or filter
+- ✅ List and describe classes
+- ✅ Basic stats via GraphQL `Aggregate`
 
-## Example
+## Basic Example
 
 ```ruby
-# Initialize client
-client = Vectra::Client.new(
-  provider: :weaviate,
-  host: 'localhost',
-  port: 8080
+require "vectra"
+
+client = Vectra.weaviate(
+  api_key: ENV["WEAVIATE_API_KEY"],
+  host: "https://your-weaviate-instance"
 )
 
+index = "Document" # Weaviate class name
+
 # Upsert vectors
 client.upsert(
+  index: index,
   vectors: [
-    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { category: 'news' } }
-  ]
+    {
+      id: "doc-1",
+      values: [0.1, 0.2, 0.3],
+      metadata: {
+        title: "Getting started with Vectra",
+        category: "docs"
+      }
+    }
+  ],
+  namespace: "prod" # stored as _namespace property
 )
 
-# Search
-results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+# Query with metadata filter
+results = client.query(
+  index: index,
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5,
+  namespace: "prod",
+  filter: { category: "docs" },
+  include_metadata: true
+)
+
+results.each do |match|
+  puts "#{match.id} (score=#{match.score.round(3)}): #{match.metadata["title"]}"
+end
+```
+
+## Advanced Filtering
+
+Vectra maps simple Ruby hashes to Weaviate `where` filters:
+
+```ruby
+results = client.query(
+  index: "Document",
+  vector: query_embedding,
+  top_k: 10,
+  filter: {
+    category: "blog",
+    views: { "$gt" => 1000 },
+    tags: ["ruby", "vectra"] # ContainsAny
+  },
+  include_metadata: true
+)
 ```
 
+Supported operators:
+
+- Equality: `{ field: "value" }` or `{ field: { "$eq" => "value" } }`
+- Inequality: `{ field: { "$ne" => "value" } }`
+- Ranges: `{ field: { "$gt" => 10 } }`, `{ "$gte" => 10 }`, `{ "$lt" => 20 }`, `{ "$lte" => 20 }`
+- Arrays: `{ field: ["a", "b"] }` (contains any), `{ field: { "$in" => ["a", "b"] } }`
+
 ## 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 |
+| Option   | Type   | Required | Description                                   |
+|----------|--------|----------|-----------------------------------------------|
+| `host`   | String | Yes      | Weaviate base URL (`http://` or `https://`)  |
+| `api_key`| String | No*      | API key if auth is enabled / cloud instances |
+
+> `api_key` is optional for local, unsecured Weaviate; required for managed/cloud deployments.
 
 ## Documentation
 

data/examples/GRAFANA_QUICKSTART.md

@@ -0,0 +1,158 @@
+# Grafana Dashboard - Quick Start for Screenshots
+
+**Get beautiful dashboard screenshots in 5 minutes!**
+
+## Step-by-Step Guide
+
+### 1. Install Dependencies
+
+```bash
+# Install prometheus-client gem
+gem install prometheus-client
+
+# Or add to Gemfile:
+# gem 'prometheus-client'
+```
+
+### 2. Start Prometheus Exporter (Terminal 1)
+
+```bash
+cd /path/to/vectra
+ruby examples/prometheus-exporter.rb
+```
+
+You should see:
+```
+🚀 Vectra Prometheus Exporter
+📊 Metrics endpoint: http://localhost:9394/metrics
+🌐 Web interface: http://localhost:9394
+```
+
+**Keep this running!**
+
+### 3. Setup Grafana Cloud
+
+1. Go to [grafana.com](https://grafana.com) and sign up (free)
+2. Create a new organization
+3. Go to **Connections** → **Data Sources**
+4. Click **Add new data source**
+5. Select **Prometheus**
+6. Configure:
+   - **Name:** `Prometheus` (or any name)
+   - **URL:** `http://localhost:9394` (if using local)
+   - OR use Grafana Cloud's Prometheus (recommended)
+7. Click **Save & Test** (should show "Data source is working")
+
+### 4. Import Dashboard
+
+1. Go to **Dashboards** → **New** → **Import**
+2. Click **Upload JSON file**
+3. Select `examples/grafana-dashboard.json`
+4. Select your Prometheus data source
+5. Click **Import**
+
+### 5. View Dashboard
+
+- Dashboard will appear with all panels
+- Wait 1-2 minutes for metrics to accumulate
+- Refresh dashboard (F5) to see new data
+
+### 6. Take Screenshots
+
+**Option A: Browser Screenshot**
+- Use browser dev tools (F12)
+- Or use screenshot tool (Cmd+Shift+4 on Mac)
+
+**Option B: Grafana Share**
+- Click panel → **Share** → **Direct link rendered image**
+- Or use **Export** → **Save as image**
+
+## Best Panels for Screenshots
+
+### 🎯 Top Recommendations:
+
+1. **Request Rate by Operation** (Time Series)
+   - Shows query, upsert, delete operations
+   - Clean lines, professional look
+   - Perfect for: Twitter, LinkedIn, blog posts
+
+2. **Latency Distribution** (P50, P95, P99)
+   - Three lines showing percentiles
+   - Shows performance depth
+   - Perfect for: Technical blog posts, documentation
+
+3. **Operations Distribution** (Pie Chart)
+   - Colorful, easy to understand
+   - Shows operation breakdown
+   - Perfect for: Overview posts, presentations
+
+4. **Top Row Stats** (4 Stat Panels)
+   - Total Requests, Error Rate, P95 Latency, Cache Hit Ratio
+   - Shows key metrics at a glance
+   - Perfect for: Hero images, feature highlights
+
+## Tips for Best Screenshots
+
+### Time Range
+- Set to **"Last 15 minutes"** for demo screenshots
+- Shows active, recent data
+
+### Theme
+- Use **Dark theme** (Settings → Preferences)
+- Looks more professional
+
+### Panel Settings
+- Hide legend if too cluttered (Panel → Options → Legend)
+- Add panel descriptions (Panel → Title → Description)
+
+### Data Density
+- Let exporter run for 2-3 minutes before screenshot
+- More data = better visualization
+
+## Troubleshooting
+
+### No Data Showing?
+
+1. **Check exporter is running:**
+   ```bash
+   curl http://localhost:9394/metrics | head -20
+   ```
+   Should show Prometheus metrics
+
+2. **Check Grafana data source:**
+   - Go to Data Sources
+   - Click "Test" button
+   - Should show "Data source is working"
+
+3. **Check dashboard queries:**
+   - Click panel → Edit
+   - Check if query returns data
+   - Try: `sum(vectra_requests_total)`
+
+### Metrics Not Appearing?
+
+- Exporter generates metrics every 0.5-2 seconds
+- Wait 1-2 minutes for data to accumulate
+- Refresh dashboard (F5)
+
+## Next Steps
+
+- Run comprehensive demo to generate real metrics:
+  ```bash
+  bundle exec ruby examples/comprehensive_demo.rb
+  ```
+
+- See [grafana-setup.md](grafana-setup.md) for production setup
+
+- Check [monitoring guide](../docs/guides/monitoring.md) for full monitoring setup
+
+## Example Screenshot Workflow
+
+1. ✅ Start exporter: `ruby examples/prometheus-exporter.rb`
+2. ✅ Import dashboard to Grafana
+3. ✅ Wait 2 minutes for data
+4. ✅ Set time range to "Last 15 minutes"
+5. ✅ Take screenshot of "Request Rate by Operation" panel
+6. ✅ Take screenshot of "Latency Distribution" panel
+7. ✅ Take screenshot of full dashboard
+8. ✅ Done! 🎉