vector_amp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5cca5e94ec6fe5fa062e6e6034a5576db8264eefb4ebc306ed489ad8946ccd6
-  data.tar.gz: ba79880edd034128d92b4a57b3a7fe46be310e0b190d3cb93f8c7a6b00d80db4
+  metadata.gz: 7147209a61689dee14e2d37581f33cad58fb5291543edb086fcafdf841e71c0a
+  data.tar.gz: c399a9373b4820d6c141362b29e2b81bc34de71a02ecb0d69c7780febdbd3674
 SHA512:
-  metadata.gz: 8a1cf8517e4862b4a240b6dc6b4da146bb2fe1499d9b2b6a98fbdefe870be57ad24c78b5defffc4986ca3babea7d8533128450d1bfc54468305c23e54bcabcc5
-  data.tar.gz: aca7d1ef6aa30ff9477fdcd30d1deab9831111a8fd759f521e0cbd2334f724d2b870e57eee393a9d0d987f19ced7c6b9a776054c54a44bd6f5b4a6f6f20c3aa1
+  metadata.gz: 6b2f983acc42db9c33801bcbe726537975af6d6ec9eab12a542a860ac5836fa417e07bb35ddfd6e4f7a55f0b6311c4ee5793d192427e5182c5fff11aae9849c4
+  data.tar.gz: 2d720c1922917177c98cf7ddab94b9f2f20ef0654e31f673d47f4283459cca5c9808851875bf2a28a40ff9f6d63a7634bd852b0a74539453c6e7dff9d4dd58b1

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,40 @@ 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"
+)
+```
+
+Declare typed metadata at creation, then merge fields or replace the complete schema:
+
+```ruby
+schema = [
+  VectorAmp::MetadataSchema.field(:category, VectorAmp::MetadataSchema::STRING),
+  VectorAmp::MetadataSchema.field(:price, VectorAmp::MetadataSchema::F32)
+]
+dataset = client.datasets.create(name: "products", metadata_schema: schema)
+dataset.patch_metadata_schema([VectorAmp::MetadataSchema.field(:inventory, VectorAmp::MetadataSchema::U32)])
+dataset.replace_metadata_schema(schema) # [] removes all declared fields
+```
+
+Canonical types are `STRING`, `U32`, `I32`, `I64`, `F32`, and `F64`.
+
 ### 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.
@@ -334,6 +374,8 @@ equivalent `datasetObj.<m>(...)` on a returned `VectorAmp::Dataset`.
 | Method | Required | Optional (defaults) |
 |---|---|---|
 | `create(name:)` | `name` | `dim` (inferred), `embedding` (vectoramp/VectorAmp-Embedding-4B), `metric` ("cosine"), `hybrid`, `filters`, `metadata_schema`, `tuning`, `metadata` |
+| `patch_metadata_schema(id, schema)` | `id`, `schema` | — |
+| `replace_metadata_schema(id, schema)` | `id`, `schema` | — |
 | `list` | — | `limit` (50), `offset` (0) |
 | `get(id)` | `id` | — |
 | `delete(id)` | `id` | — |

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.
@@ -87,13 +95,22 @@ module VectorAmp
       service.delete(id)
     end
 
+    # Add or update typed metadata fields, retaining omitted fields.
+    def patch_metadata_schema(schema)
+      service.patch_metadata_schema(id, schema)
+    end
+
+    # Replace the complete typed metadata schema.
+    def replace_metadata_schema(schema)
+      service.replace_metadata_schema(id, schema)
+    end
+
     # Fetch stats for this dataset.
     # @return [Hash] dataset statistics.
     def stats
       service.stats(id)
     end
 
-
     # List retained source documents for this dataset using cursor pagination.
     # @param limit [Integer, nil] maximum documents to return.
     # @param cursor [String, nil] cursor from a previous response's `next_cursor`.

data/lib/vector_amp/datasets.rb

@@ -59,7 +59,7 @@ module VectorAmp
     # @param metric [String] distance metric; defaults to `cosine`.
     # @param hybrid [Boolean, nil] enable hybrid (dense + sparse) search; sends `hybrid: true`.
     # @param filters [Hash, nil] optional filter schema/config.
-    # @param metadata_schema [Hash, nil] optional metadata schema.
+    # @param metadata_schema [Array<Hash>, Hash, nil] optional metadata schema.
     # @param tuning [Hash, nil] optional SABLE tuning parameters.
     # @param metadata [Hash, nil] optional dataset metadata.
     # @return [Dataset] created dataset.
@@ -85,13 +85,51 @@ module VectorAmp
         index_type: "sable",
         hybrid: hybrid,
         filters: filters,
-        metadata_schema: metadata_schema,
+        schema: normalize_metadata_schema(metadata_schema),
         tuning: tuning,
         metadata: metadata
       )
       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
+
+    # Add or update typed metadata fields, retaining omitted fields.
+    # @param dataset_id [String] dataset id.
+    # @param schema [Array<Hash>] fields with `name` and canonical `type`.
+    # @return [Dataset] updated dataset.
+    def patch_metadata_schema(dataset_id, schema)
+      update_metadata_schema(dataset_id, schema, "merge")
+    end
+
+    # Replace the complete typed metadata schema.
+    # @param dataset_id [String] dataset id.
+    # @param schema [Array<Hash>] complete field list; may be empty.
+    # @return [Dataset] updated dataset.
+    def replace_metadata_schema(dataset_id, schema)
+      update_metadata_schema(dataset_id, schema, "replace")
+    end
 
     # List retained source documents for a dataset using cursor pagination.
     # @param dataset_id [String] dataset id.
@@ -176,6 +214,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 +274,34 @@ 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 normalize_metadata_schema(schema)
+      return schema unless schema.is_a?(Hash)
+
+      schema.map do |name, config|
+        raise ArgumentError, "metadata schema field #{name.inspect} must be a Hash" unless config.is_a?(Hash)
+
+        { name: name.to_s }.merge(config)
+      end
+    end
+
+    def update_metadata_schema(dataset_id, schema, mode)
+      response = @transport.request(
+        :patch,
+        "/datasets/#{dataset_id}/schema",
+        body: { schema: schema, mode: mode }
+      )
+      wrap_dataset(response)
+    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/metadata_schema.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module VectorAmp
+  # Helpers and canonical scalar types for dataset metadata schemas.
+  module MetadataSchema
+    STRING = "string"
+    U32 = "u32"
+    I32 = "i32"
+    I64 = "i64"
+    F32 = "f32"
+    F64 = "f64"
+    TYPES = [STRING, U32, I32, I64, F32, F64].freeze
+
+    def self.field(name, type)
+      raise ArgumentError, "unsupported metadata schema type: #{type.inspect}" unless TYPES.include?(type)
+
+      { name: name.to_s, type: type }
+    end
+  end
+end

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.3.0"
 end

data/lib/vector_amp.rb

@@ -4,6 +4,8 @@ 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/metadata_schema"
 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.3.0
 platform: ruby
 authors:
 - VectorAmp
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -114,6 +114,8 @@ files:
 - lib/vector_amp/error.rb
 - lib/vector_amp/ingestion.rb
 - lib/vector_amp/intelligence.rb
+- lib/vector_amp/metadata_schema.rb
+- lib/vector_amp/org_secrets.rb
 - lib/vector_amp/schedules.rb
 - lib/vector_amp/source.rb
 - lib/vector_amp/transport/base.rb