VectorAmp Rust SDK
Idiomatic async Rust client for the public VectorAmp API.
- Default API base URL:
https://api.vectoramp.com - Auth:
X-API-Key: <api_key> - Async / await on top of
reqwestandtokio, with a smallTransporttrait so a different stack (gRPC, mocks) can be plugged in - Dataset creation always uses SABLE; the SDK intentionally does not expose an index type option
Licensed under the Apache License 2.0.
Install
# Cargo.toml
[]
= "0.1"
= { = "1", = ["macros", "rt-multi-thread"] }
Quick start
Only a name is required to create a dataset. The SDK defaults the embedding to
VectorAmp-Embedding-4B (provider vectoramp), infers the dimension (2560),
defaults the metric to cosine, and always uses the SABLE index.
use Client;
async
Client::new reads the API key you pass in; the only required input is the key,
and it is commonly read from VECTORAMP_API_KEY.
Configure the client
use Client;
let client = builder
.api_key
.base_url
.build?;
Custom HTTP client:
let http = builder
.timeout
.build?;
let client = builder
.api_key
.http_client
.build?;
Custom transport for tests or future protocols:
use Arc;
use async_trait;
use ;
;
let client = builder
.api_key
.transport
.build?;
Datasets
Create
use CreateDatasetRequest;
// Minimal: name only. Embedding config is omitted so VectorAmp uses
// the managed VectorAmp-Embedding-4B model and infers dim 2560.
let dataset = client.datasets.create.await?;
// Hybrid (dense + sparse) index.
let hybrid = client
.datasets
.create
.await?;
// Optional BYOM: use OpenAI only when you intentionally want that provider
// ("small" → 1536, "large" → 3072 inferred).
let openai = client
.datasets
.create
.await?;
// Custom / unknown model requires an explicit dim.
let custom = client
.datasets
.create
.await?;
// Store/update the org OpenAI key, then create a dataset that references it.
let openai = client
.datasets
.create_with_openai_api_key
.await?;
You can also manage the stored OpenAI key directly:
client.org_secrets.put_openai_api_key.await?;
client.org_secrets.update_openai_api_key.await?;
client.org_secrets.has_openai_api_key.await?;
// Optional typed metadata schema. Canonical types are String, U32, I32, I64,
// F32, and F64.
use ;
let schema = vec!;
let products = client.datasets.create.await?;
// Merge fields while retaining existing ones, or replace the complete schema.
client.datasets.patch_metadata_schema.await?;
client.datasets.replace_metadata_schema.await?;
CreateDatasetRequest has no index_type field. The SDK always sends
index_type: "sable". The create body field is dim (never dimension).
List / get / delete
// Pagination is optional: pass `()` for defaults, `(limit, offset)`, or a bare limit.
let page = client.datasets.list.await?;
let page = client.datasets.list.await?;
let dataset = client.datasets.get.await?;
dataset.delete.await?;
create, get, and list return Dataset resource handles bound to the
originating client. Both the object→method and service styles work:
let dataset = client.datasets.get.await?;
let resp = dataset.search.await?; // object → method (preferred)
let resp = client.datasets.search.await?; // service style
Insert vectors
Vector ids accept a string or an integer. Integer ids are serialized as JSON numbers so the API preserves them exactly.
use Vector;
dataset
.insert
.await?;
// `insert_vectors` is an alias of `insert`.
dataset.insert_vectors.await?;
// Delete vectors by id (optional write concern).
let deleted = dataset
.delete_vectors_with_write_concern
.await?;
Add texts
add_texts embeds text through the dataset embedding model, copies the source
text into metadata.text, and inserts the resulting vectors. Pass a &str,
Vec<&str>, or Vec<String> (the SDK generates text-1, text-2, … ids), or
a Vec<TextDocument> for custom ids/metadata.
use TextDocument;
dataset.add_texts.await?;
dataset
.add_texts
.await?;
Search
String queries default to top_k: 10. rerank: true expands to the full rerank
object. Hybrid search accepts sparse_query/alpha via SearchRequest.
use ;
let resp = dataset.search.await?;
let resp = dataset
.search_with
.await?;
// Vector search:
let resp = dataset.search.await?;
Source documents
Document listing is cursor-based: pass next_cursor from the previous response.
download_document returns the original bytes and follows redirects.
use DocumentListOptions;
let page = dataset
.list_documents
.await?;
for doc in &page.documents
Ingestion
Source builders
Typed builders fill in source_type, sensible defaults, and a generated name.
Supported types: web, s3, gcs, gdrive, jira, confluence,
file_upload, plus GenericSource as an escape hatch.
use ;
let web = client
.sources
.create_web
.await?;
let s3 = client
.sources
.create_s3
.await?;
let confluence = client
.sources
.create_confluence
.await?;
create_source accepts any builder directly, and the per-type
create_web/create_s3/create_gcs/create_google_drive/create_jira/create_confluence/create_file_upload/create_generic
helpers are thin wrappers over it.
Jobs
use StartIngestionRequest;
let dataset = client.datasets.get.await?;
// Create a source and start a job in one call.
let job = dataset
.ingest_new_source
.await?;
// Start a job from an existing source.
let job = dataset.ingest_source.await?;
let jobs = client.ingestion.list_jobs.await?;
let job = client.ingestion.get_job.await?;
Filesystem upload
ingest_files hides the presigned-upload flow: it creates a file_upload
source, initializes presigned uploads, PUTs the bytes, and completes the job.
use PathBuf;
let job = dataset
.ingest_files
.await?;
Intelligence / RAG
ask defaults top_k = 5, include_sources = true, and dataset scope "all"
when unscoped.
use AskOptions;
// Unscoped (defaults to all datasets).
let answer = client.ask.await?;
// Scoped to a dataset.
let answer = dataset.ask.await?;
// Explicit options.
let answer = client
.ask_with
.await?;
Streaming (SSE)
let mut stream = dataset.ask_stream.await?;
while let Some = stream.next_event.await?
Sessions
Durable RAG conversations:
let session = client.intelligence.create_session.await?;
client
.intelligence
.append_message
.await?;
let messages = client.intelligence.list_messages.await?;
let sessions = client.intelligence.list_sessions.await?;
let one = client.intelligence.get_session.await?;
Errors
Non-2xx responses surface as Error::Api(ApiError).
match client.datasets.get.await
Method reference
R = required, O = optional. Pagination arguments accept (), (limit, offset),
or a bare limit.
client.datasets() — DatasetService (and the bound Dataset object)
| Method | Args | Returns |
|---|---|---|
list(pagination) |
pagination (O) | DatasetList |
get(id) |
id (R) | Dataset |
create(req) |
name/builder/request (R) | Dataset |
delete(id) / Dataset::delete() |
id (R) | () |
search(id, input) / Dataset::search(input) |
id (R), text|vector|SearchRequest (R) |
SearchResponse |
search_with(id, input, opts) / Dataset::search_with(input, opts) |
+ SearchOptions (O) |
SearchResponse |
insert(id, vectors) / Dataset::insert(vectors) (+ insert_vectors) |
id (R), Vec<Vector> (R) |
InsertVectorsResponse |
embed(id, req) / Dataset::embed(req) |
id (R), EmbedRequest (R) |
EmbedResponse |
add_texts(id, input) / Dataset::add_texts(input) |
id (R), texts/docs (R) | AddTextsResponse |
add_texts_with(id, input, opts) / Dataset::add_texts_with(input, opts) |
+ AddTextsOptions (O) |
AddTextsResponse |
list_documents(id, opts) / Dataset::list_documents(opts) |
id (R), DocumentListOptions (O) |
DatasetDocumentList |
download_document(id, docId) / Dataset::download_document(docId) |
id (R), docId (R) | Vec<u8> |
ingest_source(id, srcId) / Dataset::ingest_source(srcId) |
id (R), srcId (R) | Job |
ingest_new_source(id, builder) / Dataset::ingest_new_source(builder) |
id (R), source builder (R) | Job |
ingest_files(id, paths, opts) / Dataset::ingest_files(paths, opts) |
id (R), paths (R), IngestFilesOptions (O) |
Job |
ask(id, query) / Dataset::ask(query) |
id (R), query (R) | AskResponse |
ask_with(id, query, opts) / Dataset::ask_with(query, opts) |
+ AskOptions (O) |
AskResponse |
ask_stream(id, query) / Dataset::ask_stream(query) |
id (R), query (R) | AskStream |
client.ask* (top level)
| Method | Args | Returns |
|---|---|---|
ask(query) |
query (R) | AskResponse |
ask_with(query, opts) |
query (R), AskOptions (O) |
AskResponse |
ask_stream(query) |
query (R) | AskStream |
client.ingestion() / client.sources() — IngestionService
| Method | Args | Returns |
|---|---|---|
list_sources(pagination) |
pagination (O) | SourceList |
get_source(id) |
id (R) | Source |
create_source(builder) |
source builder (R) | Source |
create_web/_s3/_gcs/_google_drive/_jira/_confluence/_file_upload/_generic(source) |
typed builder (R) | Source |
start_job(req) |
StartIngestionRequest (R) |
Job |
list_jobs(dataset_id, pagination) |
dataset_id (O), pagination (O) | JobList |
get_job(id) |
id (R) | Job |
retry_job(id) |
id (R) | Job |
ingest_files(dataset_id, paths, opts) |
dataset_id (R), paths (R), opts (O) | Job |
client.intelligence() — IntelligenceService
| Method | Args | Returns |
|---|---|---|
ask(query) / ask_with(query, opts) |
query (R), AskOptions (O) |
AskResponse |
stream(query, opts) |
query (R), AskOptions (O) |
AskStream |
create_session(req) |
title/CreateSessionRequest (O) |
IntelligenceSession |
list_sessions(pagination) |
pagination (O) | SessionList |
get_session(id) |
id (R) | IntelligenceSession |
delete_session(id) |
id (R) | () |
append_message(id, role, content) |
id (R), role (R), content (R) | SessionMessage |
append_message_with(id, req) |
id (R), AppendMessageRequest (R) |
SessionMessage |
list_messages(id, pagination) |
id (R), pagination (O) | MessageList |
client.schedules() — ScheduleService
| Method | Args | Returns |
|---|---|---|
list(pagination) |
pagination (O) | ScheduleList |
get(id) |
id (R) | Schedule |
create(req) |
CreateScheduleRequest (R) |
Schedule |
update(id, req) |
id (R), UpdateScheduleRequest (R) |
Schedule |
delete(id) |
id (R) | () |
trigger(id) |
id (R) | TriggerScheduleResponse |
Development
CI runs the format check, clippy, and the full test suite.