vectoramp 0.1.0__tar.gz → 0.3.0__tar.gz

vectoramp-0.3.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.3.0] - 2026-07-20
+
+### Added
+
+- Add typed metadata-schema fields when creating datasets.
+- Add metadata-schema merge/patch and full replacement operations.
+- Document create, merge, and replace schema workflows.
+
+## [0.2.0] - 2026-07-14
+
+### Added
+
+- Add dataset/vector deletion helpers for deleting vectors by id.
+- Add organization secret helpers and OpenAI-backed dataset creation convenience flow.
+- Document OpenAI secret setup and vector deletion examples.
+
+## [0.1.0] - 2026-07-02
+
+### Added
+
+- Initial public-ready package baseline for VectorAmp SDK/CLI migration to GitHub.
+- GitHub Actions CI workflow.

{vectoramp-0.1.0 → vectoramp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectoramp
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python SDK for the VectorAmp API
 Project-URL: Homepage, https://vectoramp.com
 Project-URL: Documentation, https://docs.vectoramp.com
@@ -31,9 +31,9 @@ Description-Content-Type: text/markdown
 <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>
@@ -87,7 +87,7 @@ client = VectorAmp(api_key="va_...", base_url="http://localhost:8080")
 
 ## Datasets
 
-Dataset creation always requests the SABLE index. The SDK intentionally does **not** expose an `index_type` option. Built-in helpers infer dimensions for VectorAmp 4B and OpenAI `text-embedding-3-small`/`text-embedding-3-large`.
+Dataset creation always requests the SABLE index. The SDK intentionally does **not** expose an `index_type` option. For normal use, omit embedding config and VectorAmp uses the managed `VectorAmp-Embedding-4B` model with inferred dim `2560`. Built-in helpers also infer dimensions for optional OpenAI BYOM models.
 
 The only required argument is `name`. The default embedding is `VectorAmp-Embedding-4B` (`dim=2560`, `metric="cosine"`):
 
@@ -103,17 +103,48 @@ Enable hybrid (dense + sparse) indexing with `hybrid=True`:
 dataset = client.datasets.create("product-docs", hybrid=True)
 ```
 
-Bring your own embedding model with the `openai` helper (dimension is inferred):
+Optional BYOM: use the `openai` helper only when you intentionally want an OpenAI embedding model (dimension is inferred):
 
 ```python
 from vectoramp import openai
 
 dataset = client.datasets.create(
-    "product-docs",
+    "openai-docs",
     embedding=openai("small"),  # or openai("large")
 )
 ```
 
+To save or rotate the OpenAI API key as an organization secret first, then
+create the dataset with `embedding.secret_ref`, use the helper:
+
+```python
+dataset = client.datasets.create_openai(
+    name="product-docs",
+    api_key="sk-...",
+    secret_ref="emb:openai:api_key",  # default
+)
+
+# Or upsert the secret directly.
+client.secrets.put_openai_api_key("sk-...")
+client.org_secrets.update("emb:openai:api_key", "sk-rotated")
+```
+
+Declare typed metadata at creation, then merge fields or replace the complete schema:
+
+```python
+from vectoramp import MetadataSchemaField
+
+schema: list[MetadataSchemaField] = [
+    {"name": "category", "type": "string"},
+    {"name": "price", "type": "f32"},
+]
+dataset = client.datasets.create(name="products", metadata_schema=schema)
+dataset.patch_metadata_schema([{"name": "inventory", "type": "u32"}])
+dataset.replace_metadata_schema(schema)  # [] removes all declared fields
+```
+
+Canonical field types are `string`, `u32`, `i32`, `i64`, `f32`, and `f64`.
+
 For a custom/unknown model you must pass `dim` explicitly:
 
 ```python
@@ -184,6 +215,13 @@ dataset.add_texts(
 )
 ```
 
+Delete vectors by id:
+
+```python
+dataset.delete_vectors(["doc-001", 42])
+client.datasets.delete_vectors(dataset_id, ["doc-001", 42])
+```
+
 ## Search
 
 Search by text:
@@ -412,13 +450,16 @@ listed first; optional arguments show their default.
 
 ### Datasets (`client.datasets` / `Dataset`)
 
-- `create(name, *, dim=None, metric="cosine", embedding=None, embedding_provider="vectoramp", embedding_model="VectorAmp-Embedding-4B", hybrid=False, filters=None, metadata_schema=None, tuning=None)` → `Dataset`. Always SABLE. `dim` inferred for built-in models; required for custom models.
+- `create(name, *, dim=None, metric="cosine", embedding=None, embedding_provider="vectoramp", embedding_model="VectorAmp-Embedding-4B", hybrid=False, filters=None, metadata_schema=None, tuning=None, openai_api_key=None, openai_secret_ref="emb:openai:api_key", validate_openai_key=False)` → `Dataset`. Always SABLE. `dim` inferred for built-in models; required for custom models.
 - `list(*, limit=50, offset=0)` → page with `Dataset` objects.
 - `get(dataset_id)` → `Dataset`.
+- `patch_metadata_schema(dataset_id, schema)` / `Dataset.patch_metadata_schema(schema)` → updated `Dataset`.
+- `replace_metadata_schema(dataset_id, schema)` / `Dataset.replace_metadata_schema(schema)` → updated `Dataset`.
 - `delete(dataset_id)` / `dataset.delete()`.
 - `stats(dataset_id)` / `dataset.stats()`.
 - `search(dataset_id, query=None, *, vector=None, text=None, search_text=None, top_k=10, filters=None, advanced_filters=None, embedding_provider=None, embedding_model=None, nprobe_override=None, rerank_depth_override=None, hybrid=None, sparse_query=None, alpha=None, include_embeddings=None, include_documents=None, include_metadata=None, rerank=None)` / `dataset.search(…)`. `query` accepts a string (text) or float sequence (vector); `top_k` defaults to 10.
 - `insert(dataset_id, vectors)` and `insert_vectors(dataset_id, vectors)` / `dataset.insert(vectors)`. Record `id` may be `str` or `int` (integers stay JSON numbers).
+- `delete_vectors(dataset_id, ids, *, write_concern=None)` / `dataset.delete_vectors(ids)`.
 - `embed(dataset_id, *, text=None, texts=None)` / `dataset.embed(…)`.
 - `add_texts(dataset_id, texts, *, ids=None, metadatas=None)` / `dataset.add_texts(texts, …)`. Single string or list; ids auto-generated when omitted; copies the text into `metadata.text`.
 - `list_documents(dataset_id, *, limit=50, cursor=None, status=None)` / `dataset.list_documents(…)`.

{vectoramp-0.1.0 → vectoramp-0.3.0}/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>
@@ -57,7 +57,7 @@ client = VectorAmp(api_key="va_...", base_url="http://localhost:8080")
 
 ## Datasets
 
-Dataset creation always requests the SABLE index. The SDK intentionally does **not** expose an `index_type` option. Built-in helpers infer dimensions for VectorAmp 4B and OpenAI `text-embedding-3-small`/`text-embedding-3-large`.
+Dataset creation always requests the SABLE index. The SDK intentionally does **not** expose an `index_type` option. For normal use, omit embedding config and VectorAmp uses the managed `VectorAmp-Embedding-4B` model with inferred dim `2560`. Built-in helpers also infer dimensions for optional OpenAI BYOM models.
 
 The only required argument is `name`. The default embedding is `VectorAmp-Embedding-4B` (`dim=2560`, `metric="cosine"`):
 
@@ -73,17 +73,48 @@ Enable hybrid (dense + sparse) indexing with `hybrid=True`:
 dataset = client.datasets.create("product-docs", hybrid=True)
 ```
 
-Bring your own embedding model with the `openai` helper (dimension is inferred):
+Optional BYOM: use the `openai` helper only when you intentionally want an OpenAI embedding model (dimension is inferred):
 
 ```python
 from vectoramp import openai
 
 dataset = client.datasets.create(
-    "product-docs",
+    "openai-docs",
     embedding=openai("small"),  # or openai("large")
 )
 ```
 
+To save or rotate the OpenAI API key as an organization secret first, then
+create the dataset with `embedding.secret_ref`, use the helper:
+
+```python
+dataset = client.datasets.create_openai(
+    name="product-docs",
+    api_key="sk-...",
+    secret_ref="emb:openai:api_key",  # default
+)
+
+# Or upsert the secret directly.
+client.secrets.put_openai_api_key("sk-...")
+client.org_secrets.update("emb:openai:api_key", "sk-rotated")
+```
+
+Declare typed metadata at creation, then merge fields or replace the complete schema:
+
+```python
+from vectoramp import MetadataSchemaField
+
+schema: list[MetadataSchemaField] = [
+    {"name": "category", "type": "string"},
+    {"name": "price", "type": "f32"},
+]
+dataset = client.datasets.create(name="products", metadata_schema=schema)
+dataset.patch_metadata_schema([{"name": "inventory", "type": "u32"}])
+dataset.replace_metadata_schema(schema)  # [] removes all declared fields
+```
+
+Canonical field types are `string`, `u32`, `i32`, `i64`, `f32`, and `f64`.
+
 For a custom/unknown model you must pass `dim` explicitly:
 
 ```python
@@ -154,6 +185,13 @@ dataset.add_texts(
 )
 ```
 
+Delete vectors by id:
+
+```python
+dataset.delete_vectors(["doc-001", 42])
+client.datasets.delete_vectors(dataset_id, ["doc-001", 42])
+```
+
 ## Search
 
 Search by text:
@@ -382,13 +420,16 @@ listed first; optional arguments show their default.
 
 ### Datasets (`client.datasets` / `Dataset`)
 
-- `create(name, *, dim=None, metric="cosine", embedding=None, embedding_provider="vectoramp", embedding_model="VectorAmp-Embedding-4B", hybrid=False, filters=None, metadata_schema=None, tuning=None)` → `Dataset`. Always SABLE. `dim` inferred for built-in models; required for custom models.
+- `create(name, *, dim=None, metric="cosine", embedding=None, embedding_provider="vectoramp", embedding_model="VectorAmp-Embedding-4B", hybrid=False, filters=None, metadata_schema=None, tuning=None, openai_api_key=None, openai_secret_ref="emb:openai:api_key", validate_openai_key=False)` → `Dataset`. Always SABLE. `dim` inferred for built-in models; required for custom models.
 - `list(*, limit=50, offset=0)` → page with `Dataset` objects.
 - `get(dataset_id)` → `Dataset`.
+- `patch_metadata_schema(dataset_id, schema)` / `Dataset.patch_metadata_schema(schema)` → updated `Dataset`.
+- `replace_metadata_schema(dataset_id, schema)` / `Dataset.replace_metadata_schema(schema)` → updated `Dataset`.
 - `delete(dataset_id)` / `dataset.delete()`.
 - `stats(dataset_id)` / `dataset.stats()`.
 - `search(dataset_id, query=None, *, vector=None, text=None, search_text=None, top_k=10, filters=None, advanced_filters=None, embedding_provider=None, embedding_model=None, nprobe_override=None, rerank_depth_override=None, hybrid=None, sparse_query=None, alpha=None, include_embeddings=None, include_documents=None, include_metadata=None, rerank=None)` / `dataset.search(…)`. `query` accepts a string (text) or float sequence (vector); `top_k` defaults to 10.
 - `insert(dataset_id, vectors)` and `insert_vectors(dataset_id, vectors)` / `dataset.insert(vectors)`. Record `id` may be `str` or `int` (integers stay JSON numbers).
+- `delete_vectors(dataset_id, ids, *, write_concern=None)` / `dataset.delete_vectors(ids)`.
 - `embed(dataset_id, *, text=None, texts=None)` / `dataset.embed(…)`.
 - `add_texts(dataset_id, texts, *, ids=None, metadatas=None)` / `dataset.add_texts(texts, …)`. Single string or list; ids auto-generated when omitted; copies the text into `metadata.text`.
 - `list_documents(dataset_id, *, limit=50, cursor=None, status=None)` / `dataset.list_documents(…)`.

{vectoramp-0.1.0 → vectoramp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vectoramp"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python SDK for the VectorAmp API"
 readme = "README.md"
 requires-python = ">=3.9"

{vectoramp-0.1.0 → vectoramp-0.3.0}/src/vectoramp/__init__.py

@@ -10,7 +10,7 @@ from .embeddings import (
     openai,
 )
 from .exceptions import APIError, AuthenticationError, VectorAmpError
-from .resources import Dataset
+from .resources import Dataset, OrgSecretsResource
 from .sources import (
     ConfluenceSource,
     FileUploadSource,
@@ -21,6 +21,7 @@ from .sources import (
     S3Source,
     WebSource,
 )
+from .types import MetadataFieldType, MetadataSchema, MetadataSchemaField
 
 __all__ = [
     "APIError",
@@ -34,8 +35,12 @@ __all__ = [
     "GenericSource",
     "GoogleDriveSource",
     "JiraSource",
+    "MetadataFieldType",
+    "MetadataSchema",
+    "MetadataSchemaField",
     "OPENAI_TEXT_EMBEDDING_3_LARGE",
     "OPENAI_TEXT_EMBEDDING_3_SMALL",
+    "OrgSecretsResource",
     "S3Source",
     "VectorAmp",
     "VECTORAMP_EMBEDDING_4B",

{vectoramp-0.1.0 → vectoramp-0.3.0}/src/vectoramp/client.py

@@ -9,7 +9,13 @@ from typing import Iterator, Optional, Type
 import httpx
 
 from .connections import ConnectionsResource
-from .resources import DatasetsResource, IngestionResource, IntelligenceResource, SchedulesResource
+from .resources import (
+    DatasetsResource,
+    IngestionResource,
+    IntelligenceResource,
+    OrgSecretsResource,
+    SchedulesResource,
+)
 from .transport import BaseTransport, RestTransport
 from .types import JSON, ConversationTurn
 
@@ -54,6 +60,8 @@ class VectorAmp:
         self.ingestion = IngestionResource(self.transport)
         self.sources = self.ingestion
         self.connections = ConnectionsResource(self.transport)
+        self.secrets = OrgSecretsResource(self.transport)
+        self.org_secrets = self.secrets
         self.schedules = SchedulesResource(self.transport)
         self.intelligence = IntelligenceResource(self.transport)
 

{vectoramp-0.1.0 → vectoramp-0.3.0}/src/vectoramp/resources.py

@@ -6,9 +6,16 @@ import mimetypes
 import uuid
 from collections.abc import ItemsView, KeysView, ValuesView
 from pathlib import Path
-from typing import Any, Iterator, Mapping, Optional, Sequence, Union
-
-from .embeddings import EMBEDDING_DIMENSIONS, VECTORAMP_EMBEDDING_4B
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+from urllib.parse import quote
+
+from .embeddings import (
+    EMBEDDING_DIMENSIONS,
+    OPENAI_TEXT_EMBEDDING_3_SMALL,
+    VECTORAMP_EMBEDDING_4B,
+    OpenAIEmbeddingSize,
+    openai,
+)
 from .sources import (
     ConfluenceSource,
     FileUploadSource,
@@ -21,7 +28,17 @@ from .sources import (
     WebSource,
 )
 from .transport import BaseTransport, RestTransport
-from .types import JSON, AdvancedFilter, ConversationTurn, Filters, Metric, Vector, VectorId
+from .types import (
+    JSON,
+    AdvancedFilter,
+    ConversationTurn,
+    Filters,
+    MetadataSchema,
+    MetadataSchemaInput,
+    Metric,
+    Vector,
+    VectorId,
+)
 
 PathLike = Union[str, Path]
 
@@ -137,6 +154,15 @@ class Dataset:
         """
         return self.service.insert_vectors(self.id, vectors)
 
+    def delete_vectors(
+        self,
+        ids: Sequence[VectorId],
+        *,
+        write_concern: Optional[Mapping[str, Any]] = None,
+    ) -> JSON:
+        """Delete vectors from this dataset by id."""
+        return self.service.delete_vectors(self.id, ids, write_concern=write_concern)
+
     def add_texts(
         self,
         texts: Union[str, Sequence[str]],
@@ -274,6 +300,14 @@ class Dataset:
             pipeline_id=pipeline_id,
         )
 
+    def patch_metadata_schema(self, schema: MetadataSchema) -> "Dataset":
+        """Add or update typed metadata fields while retaining other fields."""
+        return self.service.patch_metadata_schema(self.id, schema)
+
+    def replace_metadata_schema(self, schema: MetadataSchema) -> "Dataset":
+        """Replace the complete typed metadata schema."""
+        return self.service.replace_metadata_schema(self.id, schema)
+
     def get(self, key: str, default: Any = None) -> Any:
         """Return a value from the raw dataset payload, or ``default``."""
         return self.raw_data.get(key, default)
@@ -360,8 +394,11 @@ class DatasetsResource:
         embedding_model: str = VECTORAMP_EMBEDDING_4B,
         hybrid: bool = False,
         filters: Optional[Mapping[str, Any]] = None,
-        metadata_schema: Optional[Mapping[str, Any]] = None,
+        metadata_schema: Optional[MetadataSchemaInput] = None,
         tuning: Optional[Mapping[str, Any]] = None,
+        openai_api_key: Optional[str] = None,
+        openai_secret_ref: str = "emb:openai:api_key",
+        validate_openai_key: bool = False,
     ) -> Dataset:
         """Create a SABLE dataset.
 
@@ -384,13 +421,38 @@ class DatasetsResource:
             filters: Optional filter schema/configuration.
             metadata_schema: Optional metadata schema.
             tuning: Optional SABLE tuning parameters.
+            openai_api_key: Optional OpenAI API key to store as an organization
+                secret before creating the dataset. When provided, and no
+                explicit embedding is passed, the dataset uses OpenAI
+                ``text-embedding-3-small`` with ``secret_ref`` set to
+                ``openai_secret_ref``.
+            openai_secret_ref: Organization-secret name used for the OpenAI key.
+            validate_openai_key: Ask the API to validate the OpenAI key before
+                storing it. Defaults to ``False``.
 
         Returns:
             Created ``Dataset`` object.
         """
+        if openai_api_key is not None:
+            if self.client is None or not hasattr(self.client, "secrets"):
+                raise TypeError("openai_api_key requires a DatasetResource owned by VectorAmp.")
+            validation_model = str(
+                (embedding or {}).get("model") or OPENAI_TEXT_EMBEDDING_3_SMALL
+            )
+            self.client.secrets.put(
+                openai_secret_ref,
+                openai_api_key,
+                validate=validate_openai_key,
+                model=validation_model,
+            )
+            if embedding is None and embedding_provider == "vectoramp":
+                embedding = openai("small")
+
         embedding_config = {"provider": embedding_provider, "model": embedding_model}
         if embedding is not None:
             embedding_config.update(dict(embedding))
+        if openai_api_key is not None and embedding_config.get("provider") == "openai":
+            embedding_config["secret_ref"] = openai_secret_ref
         resolved_dim = dim or EMBEDDING_DIMENSIONS.get(str(embedding_config.get("model")))
         if resolved_dim is None:
             raise ValueError("dim is required for custom embedding models")
@@ -407,11 +469,67 @@ class DatasetsResource:
         if filters is not None:
             body["filters"] = dict(filters)
         if metadata_schema is not None:
-            body["metadata_schema"] = dict(metadata_schema)
+            body["schema"] = self._normalize_metadata_schema(metadata_schema)
         if tuning is not None:
             body["tuning"] = dict(tuning)
         return self._to_dataset(self._transport.request("POST", "/datasets", json_body=body))
 
+    def create_openai(
+        self,
+        *,
+        name: str,
+        api_key: str,
+        size: OpenAIEmbeddingSize = "small",
+        secret_ref: str = "emb:openai:api_key",
+        validate: bool = False,
+        dim: Optional[int] = None,
+        metric: Metric = "cosine",
+        hybrid: bool = False,
+        filters: Optional[Mapping[str, Any]] = None,
+        metadata_schema: Optional[Mapping[str, Any]] = None,
+        tuning: Optional[Mapping[str, Any]] = None,
+    ) -> Dataset:
+        """Store an OpenAI org secret, then create an OpenAI-backed dataset."""
+        embedding_config = openai(size)
+        embedding_config["secret_ref"] = secret_ref
+        return self.create(
+            name=name,
+            dim=dim,
+            metric=metric,
+            embedding=embedding_config,
+            hybrid=hybrid,
+            filters=filters,
+            metadata_schema=metadata_schema,
+            tuning=tuning,
+            openai_api_key=api_key,
+            openai_secret_ref=secret_ref,
+            validate_openai_key=validate,
+        )
+
+    def patch_metadata_schema(self, dataset_id: str, schema: MetadataSchema) -> Dataset:
+        """Add or update schema fields without removing omitted fields."""
+        body = {"schema": [dict(field) for field in schema], "mode": "merge"}
+        return self._to_dataset(
+            self._transport.request("PATCH", f"/datasets/{dataset_id}/schema", json_body=body)
+        )
+
+    def replace_metadata_schema(self, dataset_id: str, schema: MetadataSchema) -> Dataset:
+        """Replace a dataset's complete typed metadata schema."""
+        body = {"schema": [dict(field) for field in schema], "mode": "replace"}
+        return self._to_dataset(
+            self._transport.request("PATCH", f"/datasets/{dataset_id}/schema", json_body=body)
+        )
+
+    @staticmethod
+    def _normalize_metadata_schema(schema: MetadataSchemaInput) -> List[Dict[str, Any]]:
+        """Normalize the legacy field-name mapping and the canonical field array."""
+        if isinstance(schema, Mapping):
+            return [
+                {"name": name, **dict(config)}
+                for name, config in schema.items()
+            ]
+        return [dict(field) for field in schema]
+
     def delete(self, dataset_id: str) -> Any:
         """Delete a dataset and return the API response.
 
@@ -578,6 +696,23 @@ class DatasetsResource:
         """Alias for ``insert_vectors``."""
         return self.insert_vectors(dataset_id, vectors)
 
+    def delete_vectors(
+        self,
+        dataset_id: str,
+        ids: Sequence[VectorId],
+        *,
+        write_concern: Optional[Mapping[str, Any]] = None,
+    ) -> JSON:
+        """Delete vectors from a dataset by id."""
+        if not ids:
+            raise ValueError("ids must contain at least one vector id.")
+        body: JSON = {"ids": list(ids)}
+        if write_concern is not None:
+            body["write_concern"] = dict(write_concern)
+        return self._transport.request(
+            "DELETE", f"/api/v1/datasets/{dataset_id}/vectors", json_body=body
+        )
+
     def embed(
         self,
         dataset_id: str,
@@ -657,6 +792,58 @@ class DatasetsResource:
         return Dataset(self, raw_data)
 
 
+class OrgSecretsResource:
+    """Organization secret helpers."""
+
+    def __init__(self, transport: BaseTransport) -> None:
+        self._transport = transport
+
+    def put(
+        self,
+        name: str,
+        value: str,
+        *,
+        validate: bool = False,
+        model: str = OPENAI_TEXT_EMBEDDING_3_SMALL,
+    ) -> Any:
+        """Create or update an organization secret.
+
+        Stores provider credentials through the generic organization-secret
+        REST endpoint. Plaintext is sent once and is never returned by reads.
+        """
+        if not name:
+            raise ValueError("name is required.")
+        if not value:
+            raise ValueError("value is required.")
+        return self._transport.request(
+            "PUT",
+            f"/org-secrets/{quote(name, safe='')}",
+            json_body={"value": value},
+        )
+
+    def update(
+        self,
+        name: str,
+        value: str,
+        *,
+        validate: bool = False,
+        model: str = OPENAI_TEXT_EMBEDDING_3_SMALL,
+    ) -> Any:
+        """Alias for :meth:`put`; org secrets are upserted by name."""
+        return self.put(name, value, validate=validate, model=model)
+
+    def put_openai_api_key(
+        self,
+        api_key: str,
+        *,
+        secret_ref: str = "emb:openai:api_key",
+        validate: bool = False,
+        model: str = OPENAI_TEXT_EMBEDDING_3_SMALL,
+    ) -> Any:
+        """Create or update the OpenAI API key organization secret."""
+        return self.put(secret_ref, api_key, validate=validate, model=model)
+
+
 class IngestionResource:
     """Sources, upload sessions, and ingestion jobs."""
 

{vectoramp-0.1.0 → vectoramp-0.3.0}/src/vectoramp/transport.py

@@ -157,7 +157,7 @@ class RestTransport(BaseTransport):
         return urljoin(self.base_url, path.lstrip("/"))
 
     def _headers(self, headers: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
-        merged = {"X-API-Key": self.api_key, "User-Agent": "vectoramp-python/0.1.0"}
+        merged = {"X-API-Key": self.api_key, "User-Agent": "vectoramp-python/0.3.0"}
         if headers:
             merged.update(headers)
         return merged

{vectoramp-0.1.0 → vectoramp-0.3.0}/src/vectoramp/types.py

@@ -7,6 +7,18 @@ from typing import Any, Dict, List, Literal, Mapping, Optional, Sequence, TypedD
 JSON = Dict[str, Any]
 Metadata = Mapping[str, Any]
 Metric = Literal["cosine", "dot", "euclidean"]
+MetadataFieldType = Literal["string", "u32", "i32", "i64", "f32", "f64"]
+
+
+class MetadataSchemaField(TypedDict):
+    """A typed metadata field declared on a dataset."""
+
+    name: str
+    type: MetadataFieldType
+
+
+MetadataSchema = Sequence[MetadataSchemaField]
+MetadataSchemaInput = Union[MetadataSchema, Mapping[str, Mapping[str, Any]]]
 
 
 class EmbeddingConfig(TypedDict):

{vectoramp-0.1.0 → vectoramp-0.3.0}/tests/test_client.py

@@ -52,7 +52,7 @@ def test_dataset_create_forces_sable_and_auth_header() -> None:
         name="docs",
         dim=2560,
         filters={"category": "string"},
-        metadata_schema={"title": {"type": "string"}},
+        metadata_schema=[{"name": "title", "type": "string"}],
         tuning={"replicas": 1},
     )
 
@@ -64,8 +64,10 @@ def test_dataset_create_forces_sable_and_auth_header() -> None:
         "provider": "vectoramp",
         "model": "VectorAmp-Embedding-4B",
     }
+    # hybrid is not sent unless explicitly requested.
+    assert "hybrid" not in seen["body"]
     assert seen["body"]["filters"] == {"category": "string"}
-    assert seen["body"]["metadata_schema"] == {"title": {"type": "string"}}
+    assert seen["body"]["schema"] == [{"name": "title", "type": "string"}]
     assert seen["body"]["tuning"] == {"replicas": 1}
 
 
@@ -88,8 +90,47 @@ def test_dataset_create_minimal_name_only_defaults() -> None:
         "provider": "vectoramp",
         "model": "VectorAmp-Embedding-4B",
     }
-    # hybrid is not sent unless explicitly requested.
-    assert "hybrid" not in seen["body"]
+
+
+def test_dataset_create_normalizes_legacy_metadata_schema_mapping() -> None:
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = json.loads(request.content)
+        return json_response({"id": "ds_legacy"}, 201)
+
+    client = make_client(handler)
+    client.datasets.create(
+        name="legacy",
+        metadata_schema={"title": {"type": "string"}},
+    )
+
+    assert seen["body"]["schema"] == [{"name": "title", "type": "string"}]
+
+
+@pytest.mark.parametrize(
+    ("method_name", "mode"),
+    [("patch_metadata_schema", "merge"), ("replace_metadata_schema", "replace")],
+)
+def test_update_metadata_schema(method_name: str, mode: str) -> None:
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"] = request.method
+        seen["url"] = str(request.url)
+        seen["body"] = json.loads(request.content)
+        return json_response({"id": "ds_1", "schema_version": 2})
+
+    client = make_client(handler)
+    schema = [{"name": "price", "type": "f32"}]
+    dataset = getattr(client.datasets, method_name)("ds_1", schema)
+
+    assert dataset.id == "ds_1"
+    assert seen == {
+        "method": "PATCH",
+        "url": "https://api.test/datasets/ds_1/schema",
+        "body": {"schema": schema, "mode": mode},
+    }
 
 
 def test_dataset_create_hybrid() -> None:
@@ -133,6 +174,96 @@ def test_dataset_create_openai_helper_infers_dimension() -> None:
     }
 
 
+def test_dataset_create_openai_stores_secret_then_uses_secret_ref() -> None:
+    calls: list[tuple[str, str, dict[str, Any]]] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else {}
+        calls.append((request.method, request.url.path, body))
+        if request.url.path == "/org-secrets/emb%3Aopenai%3Aapi_key":
+            return httpx.Response(204)
+        return json_response({"id": "ds_openai", "index_type": "sable"}, 201)
+
+    client = make_client(handler)
+    dataset = client.datasets.create_openai(
+        name="openai-docs",
+        api_key="sk-test",
+        secret_ref="emb:openai:customer-a",
+        validate=True,
+    )
+
+    assert dataset.id == "ds_openai"
+    assert calls == [
+        (
+            "PUT",
+            "/org-secrets/emb:openai:customer-a",
+            {"value": "sk-test"},
+        ),
+        (
+            "POST",
+            "/datasets",
+            {
+                "name": "openai-docs",
+                "dim": 1536,
+                "metric": "cosine",
+                "embedding": {
+                    "provider": "openai",
+                    "model": "text-embedding-3-small",
+                    "secret_ref": "emb:openai:customer-a",
+                },
+                "index_type": "sable",
+            },
+        ),
+    ]
+
+
+def test_org_secrets_put_update_openai_key() -> None:
+    calls: list[dict[str, Any]] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(json.loads(request.content))
+        return httpx.Response(204)
+
+    client = make_client(handler)
+    assert client.secrets.put("emb:openai:api_key", "sk-new") is None
+    assert client.org_secrets.update("emb:openai:api_key", "sk-rotated") is None
+
+    assert calls[0]["value"] == "sk-new"
+    assert calls[1]["value"] == "sk-rotated"
+
+
+def test_delete_vectors_payload_and_dataset_helper() -> None:
+    calls: list[tuple[str, str, dict[str, Any]]] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else {}
+        calls.append((request.method, request.url.path, body))
+        return json_response({"deleted": 2, "ids": body.get("ids", [])})
+
+    client = make_client(handler)
+    result = client.datasets.delete_vectors(
+        "ds_1", ["vec-a", 42], write_concern={"wait": True}
+    )
+    dataset = Dataset(client.datasets, {"id": "ds_1"})
+    dataset.delete_vectors(["vec-c"])
+
+    assert result["deleted"] == 2
+    assert calls == [
+        (
+            "DELETE",
+            "/api/v1/datasets/ds_1/vectors",
+            {"ids": ["vec-a", 42], "write_concern": {"wait": True}},
+        ),
+        ("DELETE", "/api/v1/datasets/ds_1/vectors", {"ids": ["vec-c"]}),
+    ]
+
+
+def test_delete_vectors_requires_ids() -> None:
+    client = make_client(lambda request: json_response({}))
+    with pytest.raises(ValueError):
+        client.datasets.delete_vectors("ds_1", [])
+
+
 def test_list_get_delete_and_stats() -> None:
     calls = []
 

vectoramp-0.1.0/CHANGELOG.md

@@ -1,12 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-This project follows semantic versioning.
-
-## [0.1.0] - 2026-07-02
-
-### Added
-
-- Initial public-ready package baseline for VectorAmp SDK/CLI migration to GitHub.
-- GitHub Actions CI workflow.