vectoramp 0.2.0__tar.gz → 0.3.0__tar.gz

{vectoramp-0.2.0 → vectoramp-0.3.0}/CHANGELOG.md

@@ -4,6 +4,14 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectoramp
-Version: 0.2.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
@@ -129,6 +129,22 @@ 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
@@ -437,6 +453,8 @@ listed first; optional arguments show their default.
 - `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.

{vectoramp-0.2.0 → vectoramp-0.3.0}/README.md

@@ -99,6 +99,22 @@ 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
@@ -407,6 +423,8 @@ listed first; optional arguments show their default.
 - `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.

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

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

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

@@ -21,6 +21,7 @@ from .sources import (
     S3Source,
     WebSource,
 )
+from .types import MetadataFieldType, MetadataSchema, MetadataSchemaField
 
 __all__ = [
     "APIError",
@@ -34,6 +35,9 @@ __all__ = [
     "GenericSource",
     "GoogleDriveSource",
     "JiraSource",
+    "MetadataFieldType",
+    "MetadataSchema",
+    "MetadataSchemaField",
     "OPENAI_TEXT_EMBEDDING_3_LARGE",
     "OPENAI_TEXT_EMBEDDING_3_SMALL",
     "OrgSecretsResource",

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

@@ -6,7 +6,7 @@ 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 typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Union
 from urllib.parse import quote
 
 from .embeddings import (
@@ -28,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]
 
@@ -290,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)
@@ -376,7 +394,7 @@ 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",
@@ -451,7 +469,7 @@ 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))
@@ -488,6 +506,30 @@ class DatasetsResource:
             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.
 

{vectoramp-0.2.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.2.0"}
+        merged = {"X-API-Key": self.api_key, "User-Agent": "vectoramp-python/0.3.0"}
         if headers:
             merged.update(headers)
         return merged

{vectoramp-0.2.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.2.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: