vector_amp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5cca5e94ec6fe5fa062e6e6034a5576db8264eefb4ebc306ed489ad8946ccd6
-  data.tar.gz: ba79880edd034128d92b4a57b3a7fe46be310e0b190d3cb93f8c7a6b00d80db4
+  metadata.gz: 275fe25e338462efa98c327a40e334085c4cbad95e720fc3ca3adecb25afa31c
+  data.tar.gz: ec1e9abc640c9a76a2203550d277c20152828ff341bb91084594170cf572beae
 SHA512:
-  metadata.gz: 8a1cf8517e4862b4a240b6dc6b4da146bb2fe1499d9b2b6a98fbdefe870be57ad24c78b5defffc4986ca3babea7d8533128450d1bfc54468305c23e54bcabcc5
-  data.tar.gz: aca7d1ef6aa30ff9477fdcd30d1deab9831111a8fd759f521e0cbd2334f724d2b870e57eee393a9d0d987f19ced7c6b9a776054c54a44bd6f5b4a6f6f20c3aa1
+  metadata.gz: 3fa5d4c3be9cae14083865ee02cfbe99bd72712ecd3ee461db487f10a51ac9c24c6810616b8d918154f1016d6971bb9d5412327221bb983ab39e821940da1595
+  data.tar.gz: 18267f1db75a0b97685a123be17caa021594fa09f6212b6f3f99bc52554a8423e963bac34d6e0f5a266467b017d981fec0f5f6f2c6dd42ef4151ab776dc205aa

data/README.md

@@ -1,9 +1,9 @@
 <div align="center">
   <a href="https://vectoramp.com/">
     <picture>
-      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-full-light.svg">
-      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-full-dark.svg">
-      <img alt="VectorAmp Logo" src=".github/images/logo-full-dark.svg" width="50%">
+      <source media="(prefers-color-scheme: light)" srcset="https://vectoramp.com/logo-full-light.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="https://vectoramp.com/logo-full-dark.svg">
+      <img alt="VectorAmp Logo" src="https://vectoramp.com/logo-full-dark.svg" width="50%">
     </picture>
   </a>
 </div>
@@ -64,14 +64,23 @@ answer = dataset.ask("What powers VectorAmp?")
 ### Creating datasets
 
 ```ruby
-# Minimal: name only.
+# Minimal: name only. Embedding config is omitted so VectorAmp uses
+# the managed VectorAmp-Embedding-4B model and infers dim 2560.
 client.datasets.create(name: "docs")
 
 # Enable hybrid (dense + sparse) search.
 client.datasets.create(name: "docs", hybrid: true)
 
-# Use an OpenAI embedding model (dim inferred from the model).
-client.datasets.create(name: "docs", embedding: VectorAmp::Embedding.openai("large"))
+# Optional BYOM: use OpenAI only when you intentionally want that provider.
+# VectorAmp::Embedding.openai uses embedding.secret_ref "emb:openai:api_key" by default.
+client.datasets.create(name: "openai-docs", embedding: VectorAmp::Embedding.openai("large"))
+
+# Store/update the org OpenAI key, then create a dataset that references it.
+client.datasets.create_with_openai_api_key(
+  name: "openai-docs",
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  size: "small"
+)
 
 # Custom/unknown model: pass dim explicitly.
 client.datasets.create(name: "docs", embedding: { provider: "acme", model: "acme-embed" }, dim: 1024)
@@ -111,6 +120,7 @@ dataset.search(
   rerank: true # expands to vectoramp / VectorAmp-Rerank-v1
 )
 dataset.insert(vectors: [{ id: "sku-1", values: [0.1, 0.2], metadata: { category: "electronics" } }])
+dataset.delete_vectors(ids: ["sku-1"])
 dataset.add_texts(["Wireless headphones"], metadata: { category: "electronics" })
 dataset.ask("Which headphones should I buy?")
 dataset.ingest_source("source-uuid")
@@ -123,10 +133,26 @@ dataset.search("wireless headphones", hybrid: true, sparse_query: "headphones",
 client.datasets.stats("dataset-uuid")
 client.datasets.search("dataset-uuid", "wireless headphones", top_k: 10)
 client.datasets.insert("dataset-uuid", vectors: [])
+client.datasets.delete_vectors("dataset-uuid", ids: ["sku-1", 42])
 ```
 
 `client.datasets.create` intentionally does not accept `index_type`; all datasets are created with SABLE.
 
+### Organization secrets
+
+```ruby
+# Store or rotate the default OpenAI org secret used by OpenAI embedding datasets.
+client.org_secrets.put_openai_api_key(api_key: ENV.fetch("OPENAI_API_KEY"))
+
+# Optionally validate before storing, or use a custom secret_ref.
+client.org_secrets.put_openai_api_key(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  secret_ref: "emb:openai:api_key",
+  validate: true,
+  model: "text-embedding-3-small"
+)
+```
+
 ### Source documents
 
 Dataset document listing is cursor-based: pass `next_cursor` into the next request and do not assume offsets or totals. Downloads return retained original bytes and follow API/storage redirects.

data/lib/vector_amp/client.rb

@@ -5,6 +5,7 @@ require_relative "datasets"
 require_relative "error"
 require_relative "ingestion"
 require_relative "intelligence"
+require_relative "org_secrets"
 require_relative "schedules"
 require_relative "source"
 require_relative "transport/http"
@@ -19,7 +20,8 @@ module VectorAmp
     # @return [IngestionResource] ingestion/source API resource.
     # @return [IntelligenceResource] intelligence API resource.
     # @return [ConnectionsResource] managed provider connections API resource.
-    attr_reader :base_url, :datasets, :ingestion, :intelligence, :schedules, :sources, :connections
+    # @return [OrgSecretsResource] organization-scoped secret helpers.
+    attr_reader :base_url, :datasets, :ingestion, :intelligence, :schedules, :sources, :connections, :org_secrets
 
     # Create a VectorAmp API client.
     # @param api_key [String] API key; defaults to ENV["VECTORAMP_API_KEY"].
@@ -38,6 +40,7 @@ module VectorAmp
       @schedules = SchedulesResource.new(@transport)
       @intelligence = IntelligenceResource.new(@transport)
       @connections = ConnectionsResource.new(@transport)
+      @org_secrets = OrgSecretsResource.new(@transport)
       @datasets = DatasetsResource.new(@transport, client: self)
     end
 

data/lib/vector_amp/dataset.rb

@@ -71,6 +71,14 @@ module VectorAmp
       service.insert(id, vectors: vectors)
     end
 
+    # Delete one or more vectors from this dataset by id.
+    # @param ids [Array<String,Integer>] vector ids to delete.
+    # @param write_concern [String, nil] optional API write concern.
+    # @return [Hash] delete response.
+    def delete_vectors(ids:, write_concern: nil)
+      service.delete_vectors(id, ids: ids, write_concern: write_concern)
+    end
+
     # Embed and insert texts into this dataset.
     # @param texts_arg [Array<String>, nil] positional texts for convenience.
     # @param texts [Array<String>, nil] keyword texts.

data/lib/vector_amp/datasets.rb

@@ -92,6 +92,29 @@ module VectorAmp
       wrap_dataset(@transport.request(:post, "/datasets", body: body))
     end
 
+    # Store/update an OpenAI API key in org secrets, then create an OpenAI-backed dataset
+    # whose embedding config references that secret.
+    # @param name [String] dataset name.
+    # @param api_key [String] OpenAI API key to store server-side.
+    # @param size [String, Symbol] "small" or "large".
+    # @param secret_ref [String] org secret reference to write and attach to the dataset.
+    # @param validate [Boolean] validate the key before storing.
+    # @param options [Hash] forwarded to {#create}, e.g. `hybrid: true` or `metadata:`.
+    # @return [Dataset] created dataset.
+    def create_with_openai_api_key(name:, api_key:, size: "small", secret_ref: "emb:openai:api_key", validate: false, **options)
+      secrets = @client&.org_secrets || begin
+        require_relative "org_secrets"
+        OrgSecretsResource.new(@transport)
+      end
+      secrets.put_openai_api_key(
+        api_key: api_key,
+        secret_ref: secret_ref,
+        validate: validate,
+        model: openai_model(size)
+      )
+      create(name: name, embedding: Embedding.openai(size, secret_ref: secret_ref), **options)
+    end
+
 
     # List retained source documents for a dataset using cursor pagination.
     # @param dataset_id [String] dataset id.
@@ -176,6 +199,21 @@ module VectorAmp
       @transport.request(:post, "/datasets/#{dataset_id}/insert", body: { vectors: Utils.normalize_vectors(vectors) })
     end
 
+    # Delete one or more vectors from a dataset by id.
+    # @param dataset_id [String] dataset id.
+    # @param ids [Array<String,Integer>] vector ids to delete.
+    # @param write_concern [String, nil] optional API write concern.
+    # @return [Hash] delete response with `deleted` and `dataset_id`.
+    def delete_vectors(dataset_id, ids:, write_concern: nil)
+      raise ArgumentError, "ids must not be empty" if ids.nil? || ids.empty?
+
+      @transport.request(
+        :delete,
+        "/datasets/#{dataset_id}/vectors",
+        body: Utils.compact_hash(ids: ids, write_concern: write_concern)
+      )
+    end
+
     # Generate embeddings using the dataset embedding configuration.
     # @param dataset_id [String] dataset id.
     # @param text [String, nil] single text to embed.
@@ -221,6 +259,15 @@ module VectorAmp
 
     private
 
+    def openai_model(size)
+      case size.to_s
+      when "small" then "text-embedding-3-small"
+      when "large" then "text-embedding-3-large"
+      else
+        raise ArgumentError, %(openai size must be "small" or "large", got #{size.inspect})
+      end
+    end
+
     def wrap_dataset(data)
       Dataset.new(data, service: self, client: @client)
     end

data/lib/vector_amp/embedding.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "utils"
+
 module VectorAmp
   # Embedding configuration defaults and helpers.
   #
@@ -28,16 +30,17 @@ module VectorAmp
 
     # Build an OpenAI embedding configuration.
     # @param size [String, Symbol] `"small"` (text-embedding-3-small) or `"large"` (text-embedding-3-large).
-    # @return [Hash] `{ provider: "openai", model: ... }`
+    # @param secret_ref [String, nil] organization secret reference containing the OpenAI API key.
+    # @return [Hash] `{ provider: "openai", model: ..., secret_ref: ... }`
     # @raise [ArgumentError] when size is not "small" or "large".
-    def openai(size = "small")
+    def openai(size = "small", secret_ref: "emb:openai:api_key")
       model = case size.to_s
               when "small" then "text-embedding-3-small"
               when "large" then "text-embedding-3-large"
               else
                 raise ArgumentError, %(openai size must be "small" or "large", got #{size.inspect})
               end
-      { provider: "openai", model: model }
+      Utils.compact_hash(provider: "openai", model: model, secret_ref: secret_ref)
     end
 
     # Normalize a user-supplied embedding value into a config hash.

data/lib/vector_amp/org_secrets.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "utils"
+
+module VectorAmp
+  # Organization-scoped secret helpers exposed by the public API.
+  class OrgSecretsResource
+    DEFAULT_OPENAI_SECRET_REF = "emb:openai:api_key"
+
+    # @param transport [#request] API transport.
+    # @return [OrgSecretsResource]
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Store or update an organization secret by name.
+    # @param name [String] org secret reference to write.
+    # @param value [String] plaintext value sent once to the API.
+    def put(name:, value:)
+      secret_name = name.to_s.strip
+      secret_value = value.to_s.strip
+      raise ArgumentError, "name is required" if secret_name.empty?
+      raise ArgumentError, "value is required" if secret_value.empty?
+
+      @transport.request(:put, "/org-secrets/#{URI.encode_www_form_component(secret_name)}", body: { value: secret_value })
+    end
+
+    # Check whether an organization secret exists.
+    def exists?(name:)
+      secret_name = name.to_s.strip
+      raise ArgumentError, "name is required" if secret_name.empty?
+      @transport.request(:get, "/org-secrets/#{URI.encode_www_form_component(secret_name)}")
+    end
+
+    # Store or update the organization OpenAI API key.
+    # @param api_key [String] OpenAI API key to store server-side.
+    # @param secret_ref [String] org secret reference to write.
+    # @param validate [Boolean] accepted for API compatibility; generic org-secret writes do not validate.
+    # @param model [String, nil] accepted for API compatibility.
+    # @return [Hash, nil] API response; normally nil/empty for 204.
+    def put_openai_api_key(api_key:, secret_ref: DEFAULT_OPENAI_SECRET_REF, validate: false, model: nil)
+      key = api_key.to_s.strip
+      raise ArgumentError, "api_key is required" if key.empty?
+
+      put(name: secret_ref, value: key)
+    end
+
+    alias update_openai_api_key put_openai_api_key
+
+    # Check whether the default organization OpenAI API key exists.
+    # @return [Hash, nil] API response; normally nil/empty for 204.
+    def openai_api_key?
+      exists?(name: DEFAULT_OPENAI_SECRET_REF)
+    end
+  end
+end

data/lib/vector_amp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VectorAmp
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/vector_amp.rb

@@ -4,6 +4,7 @@ require_relative "vector_amp/version"
 require_relative "vector_amp/client"
 require_relative "vector_amp/embedding"
 require_relative "vector_amp/error"
+require_relative "vector_amp/org_secrets"
 require_relative "vector_amp/source"
 
 module VectorAmp

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vector_amp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - VectorAmp
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -114,6 +114,7 @@ files:
 - lib/vector_amp/error.rb
 - lib/vector_amp/ingestion.rb
 - lib/vector_amp/intelligence.rb
+- lib/vector_amp/org_secrets.rb
 - lib/vector_amp/schedules.rb
 - lib/vector_amp/source.rb
 - lib/vector_amp/transport/base.rb