Struct VectorizerClient 

pub struct VectorizerClient { /* private fields */ }

Vectorizer REST client with optional master/replica topology support. Public surface is identical to the pre-phase4 monolithic VectorizerClient; the methods are now organised across per-surface impl blocks (see module docs).

Implementations

impl VectorizerClient

pub async fn get_stats(&self) -> Result<Stats>

Aggregate collection + vector counts.

Calls GET /stats.

pub async fn get_runtime_metrics(&self) -> Result<RuntimeMetrics>

Runtime metrics snapshot for the dashboard (phase25).

Calls GET /metrics/runtime. Returns CPU, memory, active connections, rolling 60-second QPS, per-route p50/p99, 5xx error rate, and the WAL state. Requires admin auth.

pub async fn get_status(&self) -> Result<ServerStatus>

Server liveness / version / uptime.

Calls GET /status.

pub async fn get_logs(&self, params: LogsQuery) -> Result<Vec<LogEntry>>

Tail recent log lines.

Calls GET /logs?lines=N&level=LEVEL.

pub async fn get_indexing_progress(&self) -> Result<IndexingProgress>

Per-collection indexing progress.

Calls GET /indexing/progress.

pub async fn force_save_collection(&self, collection: &str) -> Result<()>

Flush one collection to disk immediately.

Calls POST /collections/{name}/force-save.

pub async fn list_empty_collections(&self) -> Result<Vec<String>>

List collections that contain zero vectors.

Calls GET /collections/empty.

pub async fn cleanup_empty_collections(&self) -> Result<CleanupReport>

Delete all empty collections in one call.

Calls DELETE /collections/cleanup.

pub async fn get_config(&self) -> Result<ConfigSnapshot>

Read the server’s current config.yml.

Calls GET /config.

pub async fn update_config(&self, patch: ConfigPatch) -> Result<ConfigSnapshot>

Overwrite the server’s config.yml (admin).

Calls POST /config with the full config object. Returns the config as echoed back by the server (free-form JSON).

pub async fn list_backups(&self) -> Result<Vec<BackupInfo>>

List all server-side backup files.

Calls GET /backups.

pub async fn create_backup( &self, request: CreateBackupRequest, ) -> Result<BackupInfo>

Create a new backup (admin).

Calls POST /backups/create with {name, collections}.

pub async fn restore_backup(&self, request: RestoreBackupRequest) -> Result<()>

Restore a backup from the server’s backup directory (admin).

Calls POST /backups/restore with {backup_id}.

pub async fn restart_server(&self) -> Result<()>

Initiate a graceful server restart (admin).

Calls POST /admin/restart. The server responds before the process actually restarts; callers should poll /health until the server is back.

pub async fn list_workspaces(&self) -> Result<Vec<WorkspaceConfig>>

List configured workspace directories.

Calls GET /workspace/list.

pub async fn get_workspace_config(&self) -> Result<WorkspaceConfig>

Read the workspace configuration file.

Calls GET /workspace/config.

pub async fn add_workspace(&self, request: AddWorkspaceRequest) -> Result<()>

Register a new workspace directory (admin).

Calls POST /workspace/add with {path, collection_name}.

pub async fn remove_workspace(&self, name: &str) -> Result<()>

Remove a registered workspace directory (admin).

Calls POST /workspace/remove with {path}.

pub async fn list_slow_queries(&self) -> Result<Vec<SlowQueryEntry>>

List slow-query ring-buffer entries (phase14).

Calls GET /slow_queries. Returns entries in the order they were recorded (oldest first). The response also carries the current ring-buffer configuration, but this method returns only the entries.

Use [set_slow_query_config] to tune the threshold and capacity.

pub async fn set_slow_query_config( &self, config: SlowQueryConfig, ) -> Result<SlowQueryConfig>

Reconfigure the slow-query ring buffer (phase14).

Calls POST /slow_queries/config with {"threshold_ms": <u64>, "capacity": <usize>}.

Existing entries are retained. If the new capacity is smaller than the current entry count the oldest entries are evicted by the server.

impl VectorizerClient

pub async fn me(&self) -> Result<User>

Return the authenticated user’s claims.

Calls GET /auth/me. Requires a valid JWT / API key on the configured transport.

pub async fn logout(&self) -> Result<()>

Invalidate the current session token.

Calls POST /auth/logout. The token is blacklisted until its natural expiry.

pub async fn refresh_token(&self) -> Result<JwtToken>

Exchange the current token for a fresh one with an extended TTL.

Calls POST /auth/refresh.

pub async fn validate_password( &self, password: &str, ) -> Result<PasswordPolicyReport>

Validate a password against the server’s password policy without creating an account.

Calls POST /auth/validate-password with {password}.

pub async fn create_api_key( &self, request: CreateApiKeyRequest, ) -> Result<ApiKey>

Create a new API key for the calling user.

Calls POST /auth/keys. The api_key field in the returned ApiKey is only present at creation time — store it securely.

pub async fn list_api_keys(&self) -> Result<Vec<ApiKey>>

List the API keys belonging to the calling user.

Calls GET /auth/keys. The api_key field is omitted in list responses for security.

pub async fn revoke_api_key(&self, id: &str) -> Result<()>

Revoke an API key by id.

Calls DELETE /auth/keys/{id}. Admin can revoke any key; regular users can only revoke their own.

pub async fn create_user(&self, request: CreateUserRequest) -> Result<User>

Create a new user (admin only).

Calls POST /auth/users. Requires Role::Admin.

pub async fn list_users(&self) -> Result<Vec<User>>

List all users (admin only).

Calls GET /auth/users. Requires Role::Admin.

pub async fn delete_user(&self, username: &str) -> Result<()>

Delete a user (admin only).

Calls DELETE /auth/users/{username}. Requires Role::Admin. The server refuses to delete self or the last admin.

pub async fn change_password( &self, username: &str, new_password: &str, ) -> Result<()>

Change a user’s password.

Calls PUT /auth/users/{username}/password with {new_password}. Admins can change any password; non-admins must also supply current_password.

pub async fn rotate_api_key(&self, id: &str) -> Result<RotatedKey>

Atomically rotate an API key (admin only).

Calls POST /auth/keys/{id}/rotate with an empty body. Returns both the old and new tokens plus a grace window during which the old token remains valid.

pub async fn create_scoped_api_key( &self, request: CreateScopedApiKeyRequest, ) -> Result<ApiKey>

Create an API key with optional per-collection scopes.

Calls POST /auth/keys. When scopes is non-empty the key is restricted to the listed collections. When empty the key is default-deny on scope-enforced routes.

pub async fn update_api_key_permissions( &self, id: &str, request: UpdateApiKeyPermissionsRequest, ) -> Result<ApiKeyView>

Replace permissions (and optionally scopes) on an existing API key without rotating the credential. Admin-only.

Calls PUT /auth/keys/{id}/permissions. Returns the updated key view with the live usage_count stamped in.

key_hash, id, user_id, and created_at are immutable — rotate the key with rotate_api_key if those need to change.

pub async fn get_api_key_usage( &self, id: &str, window_days: Option<usize>, ) -> Result<ApiKeyUsageReport>

Fetch the per-day usage time-series for an API key. Admin-only.

Calls GET /auth/keys/{id}/usage?window={days}. days is clamped server-side to 1..=30; None defaults to 7. The response carries the live key view, the bucket array (oldest first, including zero-count days), and the window total.

pub async fn introspect_token(&self, token: &str) -> Result<TokenIntrospection>

Introspect a token — RFC 7662.

Calls POST /auth/introspect with {token}. Requires authentication but NOT admin. Returns active: false for any unrecognized token.

pub async fn list_audit_log(&self, query: AuditQuery) -> Result<Vec<AuditEntry>>

Query the admin audit log (admin only).

Calls GET /auth/audit with optional query parameters. Returns entries newest-first, bounded by query.limit (server default 200).

impl VectorizerClient

pub async fn list_collections(&self) -> Result<Vec<Collection>>

List every collection visible to the authenticated principal. Accepts both the legacy bare-array response and the newer {collections: [...]} wrapper.

pub async fn create_collection( &self, name: &str, dimension: usize, metric: Option<SimilarityMetric>, ) -> Result<CollectionInfo>

Create a new collection. The returned CollectionInfo is synthesised from the server’s create-response plus the arguments — the server response only carries the collection name today.

pub async fn delete_collection(&self, name: &str) -> Result<()>

Delete a collection by name.

pub async fn get_collection_info( &self, collection: &str, ) -> Result<CollectionInfo>

Fetch metadata for a collection (vector count, dimension, metric, timestamps, indexing status).

pub async fn reencode_collection( &self, collection: &str, target_encoding: &str, ) -> Result<ReencodeJob>

Re-quantize an existing collection in-place without re-embedding (phase13).

Calls POST /collections/{name}/reencode with {"target_encoding": "<encoding>"}. Valid encoding values: "sq8", "binary", "fp32".

The server runs the reencode synchronously and returns {job_id, collection, state, target_encoding, progress} on completion. state will be "completed" on success.

pub async fn set_collection_ttl( &self, collection: &str, ttl_secs: Option<u64>, ) -> Result<()>

Set or clear a per-collection TTL (phase13).

Calls POST /collections/{name}/ttl with {"ttl_secs": <secs>}. Pass None to clear the collection-level TTL. Existing vectors are NOT retroactively expired; only subsequent insertions that carry __expires_at in their payload are affected.

For per-vector expiry use set_vector_expiry on the vectors surface.

pub async fn rename_collection( &self, collection: &str, new_name: &str, ) -> Result<()>

Atomically rename a collection (phase14).

Calls POST /collections/{name}/rename with {"new_name": "<name>"}.

The server keeps the old name as an in-memory alias for one minor version so existing clients keep working without reconfiguration. The alias does not survive a restart.

pub async fn reindex_collection( &self, collection: &str, params: ReindexParams, ) -> Result<ReindexJob>

Rebuild the HNSW index with new parameters (phase14).

Calls POST /collections/{name}/reindex with {"m": u32, "ef_construction": u32, "ef_search": u32}.

No re-embedding is required — the existing stored vectors are used. The server holds the collection write-lock for the duration, so concurrent inserts queue behind the swap.

Returns a ReindexJob with state == "completed" on success.

pub async fn snapshot_collection_native( &self, collection: &str, ) -> Result<NativeSnapshotInfo>

Create a native per-collection snapshot (phase14).

Calls POST /collections/{name}/snapshot (empty body).

The server writes a gzip-compressed JSON snapshot under <data_dir>/collection_snapshots/<name>/ and returns the snapshot metadata.

pub async fn list_collection_snapshots_native( &self, collection: &str, ) -> Result<Vec<NativeSnapshotInfo>>

List all native snapshots for a collection (phase14).

Calls GET /collections/{name}/snapshots.

Returns snapshots newest-first as reported by the server.

pub async fn restore_collection_snapshot_native( &self, collection: &str, snapshot_id: &str, ) -> Result<()>

Restore a collection from a native snapshot (phase14).

Calls POST /collections/{name}/snapshots/{id}/restore (empty body).

Drops the current in-memory state and replaces it with the snapshot data.

impl VectorizerClient

pub async fn health_check(&self) -> Result<HealthStatus>

Check server health.

pub async fn login(&self, username: &str, password: &str) -> Result<JwtToken>

Exchange a (username, password) pair for a JWT via POST /auth/login. The returned token is not retained by self — the transport was built with whatever credential (or none) was passed at construction. To use the JWT for subsequent requests, construct a new client with ClientConfig::api_key = Some(jwt.access_token); the HTTP transport recognises the three-segment JWT shape and sends it as Authorization: Bearer … rather than X-API-Key.

When the server runs with auth.enabled: false this endpoint may 404 — callers running against a no-auth dev server don’t need to call login at all.

impl VectorizerClient

pub async fn discover( &self, query: &str, include_collections: Option<Vec<String>>, exclude_collections: Option<Vec<String>>, max_bullets: Option<usize>, broad_k: Option<usize>, focus_k: Option<usize>, ) -> Result<Value>

End-to-end discovery pipeline with intelligent search and LLM-style bullet generation.

pub async fn filter_collections( &self, query: &str, include: Option<Vec<String>>, exclude: Option<Vec<String>>, ) -> Result<Value>

Pre-filter collections by name patterns.

pub async fn score_collections( &self, query: &str, name_match_weight: Option<f32>, term_boost_weight: Option<f32>, signal_boost_weight: Option<f32>, ) -> Result<Value>

Rank collections by relevance to a query. The three weights must each be in [0.0, 1.0] when supplied.

pub async fn expand_queries( &self, query: &str, max_expansions: Option<usize>, include_definition: Option<bool>, include_features: Option<bool>, include_architecture: Option<bool>, ) -> Result<Value>

Generate query variations (definition / features / architecture-style expansions, capped by max_expansions).

pub async fn broad_discovery( &self, request: BroadDiscoveryRequest, ) -> Result<BroadDiscoveryResponse>

Broad multi-query search across all collections.

Calls POST /discovery/broad_discovery with {queries, k?}.

pub async fn semantic_focus( &self, request: SemanticFocusRequest, ) -> Result<SemanticFocusResponse>

Focused semantic search within a single collection.

Calls POST /discovery/semantic_focus with {collection, queries, k?}.

pub async fn promote_readme( &self, request: PromoteReadmeRequest, ) -> Result<PromoteReadmeResponse>

Promote README-quality chunks to the top of a result set.

Calls POST /discovery/promote_readme with {chunks}.

pub async fn compress_evidence( &self, request: CompressEvidenceRequest, ) -> Result<CompressEvidenceResponse>

Compress a chunk set into a concise bullet list.

Calls POST /discovery/compress_evidence with {chunks, max_bullets?, max_per_doc?}.

pub async fn build_answer_plan( &self, request: AnswerPlanRequest, ) -> Result<AnswerPlan>

Organise bullets into a structured answer plan.

Calls POST /discovery/build_answer_plan with {bullets}.

pub async fn render_llm_prompt( &self, request: RenderPromptRequest, ) -> Result<LlmPrompt>

Render an answer plan into a final LLM prompt string.

Calls POST /discovery/render_llm_prompt with {plan}.

impl VectorizerClient

pub async fn get_file_content( &self, collection: &str, file_path: &str, max_size_kb: Option<usize>, ) -> Result<Value>

Retrieve the complete content of an indexed file.

pub async fn list_files_in_collection( &self, collection: &str, filter_by_type: Option<Vec<String>>, min_chunks: Option<usize>, max_results: Option<usize>, sort_by: Option<&str>, ) -> Result<Value>

List indexed files in a collection, optionally filtered by extension and minimum chunk count.

pub async fn get_file_summary( &self, collection: &str, file_path: &str, summary_type: Option<&str>, max_sentences: Option<usize>, ) -> Result<Value>

Get an extractive or structural summary of one indexed file.

pub async fn get_file_chunks_ordered( &self, collection: &str, file_path: &str, start_chunk: Option<usize>, limit: Option<usize>, include_context: Option<bool>, ) -> Result<Value>

Retrieve chunks in original file order for progressive reading. Pair with start_chunk + limit to page.

pub async fn get_project_outline( &self, collection: &str, max_depth: Option<usize>, include_summaries: Option<bool>, highlight_key_files: Option<bool>, ) -> Result<Value>

Generate a hierarchical project structure overview.

pub async fn get_related_files( &self, collection: &str, file_path: &str, limit: Option<usize>, similarity_threshold: Option<f32>, include_reason: Option<bool>, ) -> Result<Value>

Find semantically-related files by vector similarity.

pub async fn search_by_file_type( &self, collection: &str, query: &str, file_types: Vec<String>, limit: Option<usize>, return_full_files: Option<bool>, ) -> Result<Value>

Semantic search filtered by file type. Empty file_types is rejected — pass at least one extension.

pub async fn upload_file( &self, file_bytes: Vec<u8>, filename: &str, collection_name: &str, options: UploadFileOptions, ) -> Result<FileUploadResponse>

Upload a file for automatic text extraction, chunking, and indexing.

Arguments

• file_bytes - File content as bytes
• filename - Name of the file (used for extension detection)
• collection_name - Target collection name
• options - Upload options (chunk size, overlap, metadata)

Example

use vectorizer_sdk::{VectorizerClient, ClientConfig, UploadFileOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig::default();
    let client = VectorizerClient::new(config)?;

    let file_bytes = std::fs::read("document.pdf")?;
    let options = UploadFileOptions::default();

    let response = client.upload_file(
        file_bytes,
        "document.pdf",
        "my-docs",
        options
    ).await?;

    println!("Uploaded: {} chunks created", response.chunks_created);
    Ok(())
}

pub async fn upload_file_content( &self, content: &str, filename: &str, collection_name: &str, options: UploadFileOptions, ) -> Result<FileUploadResponse>

Upload file content directly as a string. Convenience wrapper around Self::upload_file.

Example

use vectorizer_sdk::{VectorizerClient, ClientConfig, UploadFileOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VectorizerClient::new(ClientConfig::default())?;
    let code = r#"fn main() { println!("Hello!"); }"#;
    let response = client.upload_file_content(
        code, "main.rs", "rust-code", UploadFileOptions::default()
    ).await?;
    println!("Uploaded: {} vectors created", response.vectors_created);
    Ok(())
}

pub async fn get_upload_config(&self) -> Result<FileUploadConfig>

Get file upload configuration from the server (max file size, allowed extensions, default chunk settings).

Example

use vectorizer_sdk::{VectorizerClient, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VectorizerClient::new(ClientConfig::default())?;
    let upload_config = client.get_upload_config().await?;
    println!("Max file size: {}MB", upload_config.max_file_size_mb);
    Ok(())
}

impl VectorizerClient

pub async fn list_graph_nodes( &self, collection: &str, ) -> Result<ListNodesResponse>

List every node in a collection’s graph.

pub async fn get_graph_neighbors( &self, collection: &str, node_id: &str, ) -> Result<GetNeighborsResponse>

Get neighbours of a specific node.

pub async fn find_related_nodes( &self, collection: &str, node_id: &str, request: FindRelatedRequest, ) -> Result<FindRelatedResponse>

Find related nodes within N hops.

pub async fn find_graph_path( &self, request: FindPathRequest, ) -> Result<FindPathResponse>

Find the shortest path between two nodes.

pub async fn create_graph_edge( &self, request: CreateEdgeRequest, ) -> Result<CreateEdgeResponse>

Create an explicit edge between two nodes.

pub async fn delete_graph_edge(&self, edge_id: &str) -> Result<()>

Delete an edge by id.

pub async fn list_graph_edges( &self, collection: &str, ) -> Result<ListEdgesResponse>

List every edge in a collection.

pub async fn discover_graph_edges( &self, collection: &str, request: DiscoverEdgesRequest, ) -> Result<DiscoverEdgesResponse>

Discover SIMILAR_TO edges for an entire collection.

pub async fn discover_graph_edges_for_node( &self, collection: &str, node_id: &str, request: DiscoverEdgesRequest, ) -> Result<DiscoverEdgesResponse>

Discover SIMILAR_TO edges for one specific node.

pub async fn get_graph_discovery_status( &self, collection: &str, ) -> Result<DiscoveryStatusResponse>

Get discovery status for a collection.

impl VectorizerClient

pub async fn list_user_backups(&self, user_id: &str) -> Result<Vec<UserBackup>>

List all backups owned by a user.

Calls GET /hub/backups?user_id={user_id}.

pub async fn create_user_backup( &self, request: CreateUserBackupRequest, ) -> Result<UserBackup>

Create a new backup for a user.

Calls POST /hub/backups with {user_id, name, description?, collections?}.

pub async fn restore_user_backup( &self, request: RestoreUserBackupRequest, ) -> Result<()>

Restore a previously created user backup.

Calls POST /hub/backups/restore.

pub async fn upload_user_backup( &self, request: UploadUserBackupRequest, ) -> Result<UserBackup>

Upload a backup file (raw bytes).

Calls POST /hub/backups/upload?user_id={user_id}&name={name}.

The request body is sent as raw bytes via a POST. The SDK sends the binary data as a JSON-encoded base64 string because the underlying Transport::post takes Option<&serde_json::Value>. Callers that need true multipart uploads should use the HTTP transport directly via reqwest.

pub async fn get_user_backup( &self, user_id: &str, backup_id: &str, ) -> Result<UserBackup>

Fetch metadata for a single backup.

Calls GET /hub/backups/{backup_id}?user_id={user_id}.

pub async fn delete_user_backup( &self, user_id: &str, backup_id: &str, ) -> Result<()>

Delete a user backup by id.

Calls DELETE /hub/backups/{backup_id}?user_id={user_id}.

pub async fn download_user_backup( &self, user_id: &str, backup_id: &str, ) -> Result<Vec<u8>>

Download the raw binary data for a backup.

Calls GET /hub/backups/{backup_id}/download?user_id={user_id}.

The transport layer returns the response body as a String; the SDK re-encodes as UTF-8 bytes. For compressed binary backups the caller should use the raw HTTP client.

pub async fn get_usage_statistics( &self, user_id: &str, ) -> Result<UsageStatistics>

Get aggregate usage statistics for a user.

Calls GET /hub/usage/statistics?user_id={user_id}.

pub async fn get_quota_info(&self, user_id: &str) -> Result<QuotaInfo>

Get quota information for a user.

Calls GET /hub/usage/quota?user_id={user_id}.

pub async fn validate_hub_api_key( &self, key: &str, ) -> Result<HubApiKeyValidation>

Validate a HiveHub API key.

Calls POST /hub/validate-key. The key is sent in the Authorization: Bearer <key> header by the transport layer when api_key is configured on the client; the key parameter here is forwarded in the request body for callers that need to validate a different key than the one on the client.

impl VectorizerClient

pub async fn qdrant_list_collections(&self) -> Result<Value>

List all collections (Qdrant-compatible).

pub async fn qdrant_get_collection(&self, name: &str) -> Result<Value>

Get one collection’s metadata (Qdrant-compatible).

pub async fn qdrant_create_collection( &self, name: &str, config: &Value, ) -> Result<Value>

Create a collection (Qdrant-compatible).

pub async fn qdrant_upsert_points( &self, collection: &str, points: &Value, wait: bool, ) -> Result<Value>

Upsert points into a collection (Qdrant-compatible).

pub async fn qdrant_search_points( &self, collection: &str, vector: &[f32], limit: Option<usize>, filter: Option<&Value>, with_payload: bool, with_vector: bool, ) -> Result<Value>

Search points (Qdrant-compatible).

pub async fn qdrant_delete_points( &self, collection: &str, point_ids: &[Value], wait: bool, ) -> Result<Value>

Delete points by id (Qdrant-compatible).

pub async fn qdrant_retrieve_points( &self, collection: &str, point_ids: &[Value], with_payload: bool, with_vector: bool, ) -> Result<Value>

Retrieve points by id (Qdrant-compatible).

pub async fn qdrant_count_points( &self, collection: &str, filter: Option<&Value>, ) -> Result<Value>

Count points (Qdrant-compatible).

pub async fn qdrant_list_collection_snapshots( &self, collection: &str, ) -> Result<Value>

List snapshots for a collection (Qdrant-compatible).

pub async fn qdrant_create_collection_snapshot( &self, collection: &str, ) -> Result<Value>

Create a snapshot for a collection (Qdrant-compatible).

pub async fn qdrant_delete_collection_snapshot( &self, collection: &str, snapshot_name: &str, ) -> Result<Value>

Delete a snapshot (Qdrant-compatible).

pub async fn qdrant_recover_collection_snapshot( &self, collection: &str, location: &str, ) -> Result<Value>

Recover a collection from a snapshot location (Qdrant-compatible).

pub async fn qdrant_list_all_snapshots(&self) -> Result<Value>

List all snapshots across collections (Qdrant-compatible).

pub async fn qdrant_create_full_snapshot(&self) -> Result<Value>

Create a full-cluster snapshot (Qdrant-compatible).

pub async fn qdrant_list_shard_keys(&self, collection: &str) -> Result<Value>

List shard keys for a collection (Qdrant-compatible).

pub async fn qdrant_create_shard_key( &self, collection: &str, shard_key: &Value, ) -> Result<Value>

Create a shard key (Qdrant-compatible).

pub async fn qdrant_delete_shard_key( &self, collection: &str, shard_key: &Value, ) -> Result<Value>

Delete a shard key (Qdrant-compatible).

pub async fn qdrant_get_cluster_status(&self) -> Result<Value>

Get cluster status (Qdrant-compatible).

pub async fn qdrant_cluster_recover(&self) -> Result<Value>

Trigger a cluster recovery on the current peer (Qdrant-compatible).

pub async fn qdrant_remove_peer(&self, peer_id: &str) -> Result<Value>

Remove a peer from the cluster (Qdrant-compatible).

pub async fn qdrant_list_metadata_keys(&self) -> Result<Value>

List metadata keys (Qdrant-compatible).

pub async fn qdrant_get_metadata_key(&self, key: &str) -> Result<Value>

Get one metadata key (Qdrant-compatible).

pub async fn qdrant_update_metadata_key( &self, key: &str, value: &Value, ) -> Result<Value>

Update one metadata key (Qdrant-compatible).

pub async fn qdrant_query_points( &self, collection: &str, request: &Value, ) -> Result<Value>

Query points using the Qdrant 1.7+ Query API.

pub async fn qdrant_batch_query_points( &self, collection: &str, request: &Value, ) -> Result<Value>

Batch-query points using the Qdrant 1.7+ Query API.

pub async fn qdrant_query_points_groups( &self, collection: &str, request: &Value, ) -> Result<Value>

Query points with grouping (Qdrant 1.7+ Query API).

pub async fn qdrant_search_points_groups( &self, collection: &str, request: &Value, ) -> Result<Value>

Search points with grouping (Qdrant Search Groups API).

pub async fn qdrant_search_matrix_pairs( &self, collection: &str, request: &Value, ) -> Result<Value>

Search matrix pairs (Qdrant Search Matrix API).

pub async fn qdrant_search_matrix_offsets( &self, collection: &str, request: &Value, ) -> Result<Value>

Search matrix offsets (Qdrant Search Matrix API).

impl VectorizerClient

pub async fn get_replication_status(&self) -> Result<ReplicationStatus>

Get the current replication status and role of this node.

Calls GET /replication/status.

pub async fn configure_replication( &self, config: ReplicationConfig, ) -> Result<()>

Configure this node’s replication role and parameters.

Calls POST /replication/configure with the full ReplicationConfig. A server restart is required for the new config to take effect.

pub async fn get_replication_stats(&self) -> Result<ReplicationStats>

Get raw replication statistics for the active replication node.

Calls GET /replication/stats. Returns an error when replication is not enabled on this node.

pub async fn list_replicas(&self) -> Result<Vec<ReplicaInfo>>

List the replica nodes connected to this master.

Calls GET /replication/replicas. Only available on master nodes; returns an error otherwise.

pub async fn cluster_failover(&self, replica_id: &str) -> Result<FailoverReport>

Trigger a failover — promote a replica to primary.

Calls POST /cluster/failover with {replica_id}. Returns 409 from the server when the replica’s WAL lag exceeds the configured threshold.

pub async fn cluster_resync_replica( &self, replica_id: &str, ) -> Result<ResyncJob>

Force a full resync on a replica.

Calls POST /cluster/replicas/{id}/resync with an empty body.

pub async fn cluster_add_peer( &self, request: AddPeerRequest, ) -> Result<PeerInfo>

Add a peer to the cluster.

Calls POST /cluster/peers with {address, role}.

pub async fn cluster_rebalance(&self) -> Result<RebalanceJob>

Trigger a shard rebalance across all active cluster nodes.

Calls POST /cluster/rebalance with an empty body. Returns 400 when fewer than 2 active nodes are present, or 400 when a rebalance is already in progress.

pub async fn cluster_rebalance_status(&self) -> Result<Option<RebalanceJob>>

Return progress of the active (or last completed) rebalance job.

Calls GET /cluster/rebalance/status. Returns None when no rebalance has been triggered on this node.

impl VectorizerClient

pub async fn search_vectors( &self, collection: &str, query: &str, limit: Option<usize>, score_threshold: Option<f32>, ) -> Result<SearchResponse>

Text search against one collection. The server embeds the query with the collection’s provider, runs ANN search, and returns up to limit (default 10) hits scored above the optional score_threshold.

pub async fn intelligent_search( &self, request: IntelligentSearchRequest, ) -> Result<IntelligentSearchResponse>

Intelligent search — multi-query expansion + MMR diversification + domain term boosting.

pub async fn semantic_search( &self, request: SemanticSearchRequest, ) -> Result<SemanticSearchResponse>

Semantic search — advanced reranking + similarity-threshold filtering on top of the base text search.

pub async fn contextual_search( &self, request: ContextualSearchRequest, ) -> Result<ContextualSearchResponse>

Context-aware search with metadata filtering and contextual reranking.

pub async fn multi_collection_search( &self, request: MultiCollectionSearchRequest, ) -> Result<MultiCollectionSearchResponse>

Multi-collection search with cross-collection reranking and aggregation.

pub async fn search_by_file( &self, collection: &str, request: SearchByFileRequest, ) -> Result<SearchResponse>

Search a collection for vectors associated with a given file path.

Calls POST /collections/{name}/search/file with {file_path, limit?}. Returns a SearchResponse (may be empty if the file is not indexed).

pub async fn explain_search( &self, collection: &str, request: ExplainRequest, ) -> Result<ExplainResponse>

Run a search and return the full HNSW execution trace (phase14).

Calls POST /collections/{name}/explain with {"vector": [f32…], "k": <u64>}.

The trace includes: visited_nodes, ef_search, hnsw_search_ms, payload_filter_evals, quantization_score_ms, and total_ms. The results are identical to a normal search — there is no separate explain engine; the real code path is instrumented.

pub async fn hybrid_search( &self, request: HybridSearchRequest, ) -> Result<HybridSearchResponse>

Hybrid search combining dense and sparse vectors with one of three scoring algorithms (RRF, weighted, alpha-blending).

impl VectorizerClient

pub async fn get_vector( &self, collection: &str, vector_id: &str, ) -> Result<Vector>

Fetch one vector by id.

Server caveat (observed on hivehub/vectorizer:3.0.x): the GET /collections/{c}/vectors/{id} endpoint currently returns HTTP 200 with a synthetic uniform-vector payload ([0.1, 0.1, …]) even for ids that don’t exist. Callers that need real miss detection should probe via VectorizerClient::list_vectors or search and not trust an Ok(Vector) as proof of existence until the server fix ships.

pub async fn insert_texts( &self, collection: &str, texts: Vec<BatchTextRequest>, ) -> Result<BatchResponse>

Insert a batch of texts into a collection. The server embeds each entry with the collection’s configured provider (BM25 by default; FastEmbed ONNX when selected in config.yml).

Wire contract: the server’s POST /insert_texts handler expects { "collection": "<name>", "texts": [...] } — the collection is a top-level field in the JSON body, not a path segment. The earlier POST /collections/{c}/documents path this method used was never served (the 3.0.x server returns 404 for it) and has been removed.

Per-entry id field: the server reassigns every inserted vector a server-generated UUID regardless of what the caller sent. The original client id is stashed as client_id on the response entry. Callers that need idempotency by client id should key off the client_id round-trip, not the server-assigned UUID.

pub async fn delete_vector( &self, collection: &str, vector_id: &str, ) -> Result<()>

Delete a single vector by id from a collection.

Calls DELETE /collections/{collection}/vectors/{vector_id}. Returns Ok(()) on 2xx; the server treats “not found” as a 4xx that surfaces as a VectorizerError::NotFound-class error via the shared error mapper.

Companion to Self::delete_vectors (batch) and Self::move_to_collection (cross-collection move). See issue #265 for the tier-demotion use case.

pub async fn delete_vectors( &self, collection: &str, ids: &[String], ) -> Result<DeleteReport>

Delete a batch of vectors from a single collection. Per-id failures (e.g. not-found) are captured in DeleteReport::results without aborting the batch.

Calls POST /batch_delete with {"collection": ..., "ids": [...]}.

pub async fn move_to_collection( &self, src: &str, dst: &str, ids: &[String], ) -> Result<MoveReport>

Move vectors from src to dst without re-embedding (issue #265).

Calls POST /collections/{src}/vectors/move with {"destination": dst, "ids": [...]}. Server invariant: the destination insert lands BEFORE the source delete, so a mid-batch crash leaves a recoverable duplicate (never data loss). Per-id outcomes (ok, missing_in_src, dst_insert_failed, src_delete_failed) populate MoveReport::results without aborting the batch.

Typical use: tier-demotion pruner that walks a hot collection and relocates aged vectors to a warm/cold collection.

pub async fn update_vector( &self, collection: &str, id: &str, request: UpdateVectorRequest, ) -> Result<Vector>

Update a vector’s metadata in-place.

Calls POST /update with {collection, id, ...metadata}. Returns the server’s confirmation as a synthetic Vector.

Server contract (PUT /vectors): the handler accepts id and collection from the JSON body, invalidates the cache, and returns {message}. The SDK synthesises a minimal Vector from the request parameters because the server does not echo back the full vector payload.

pub async fn insert_text( &self, collection: &str, id: &str, text: &str, metadata: Option<Value>, ) -> Result<Vector>

Insert a single text document into a collection (auto-chunking when the text is long).

Calls POST /insert with {collection, id?, text, metadata?}. Returns the first vector id created as a synthetic Vector.

Server response: {message, vectors_created, vector_ids, collection, chunked}.

pub async fn list_vectors( &self, collection: &str, page: Option<u32>, limit: Option<u32>, ) -> Result<VectorPage>

List vectors in a collection with pagination.

Calls GET /collections/{name}/vectors?page=&limit=.

Note: the server handler uses offset (not page) as the query parameter. page is translated to offset = page * limit by the SDK. Pass page=None and limit=None for the server defaults (limit=10, offset=0).

pub async fn get_vector_by_path( &self, collection: &str, id: &str, ) -> Result<Vector>

Fetch a single vector by id via the path-based GET endpoint.

Calls GET /collections/{name}/vectors/{id}.

This is distinct from get_vector which uses the older POST /vector shape. The path-based handler currently returns a synthetic uniform-vector payload — see the server handler doc for the caveat.

pub async fn batch_insert_texts( &self, collection: &str, items: Vec<BatchInsertItem>, ) -> Result<BatchInsertReport>

Batch-insert multiple text documents into a collection.

Calls POST /batch_insert with {collection, texts: [...]}. Returns aggregate insert counts in BatchInsertReport.

pub async fn insert_vectors( &self, collection: &str, vectors: Vec<RawVectorInsert>, ) -> Result<BatchInsertReport>

Bulk-insert pre-computed embeddings.

Calls POST /insert_vectors with {collection, vectors: [...]}. Skips the server-side embedding pipeline entirely; the caller supplies raw Vec<f32> embeddings.

pub async fn batch_search( &self, collection: &str, requests: Vec<BatchSearchQuery>, ) -> Result<Vec<SearchResponse>>

Run multiple search queries against one collection in a single round-trip.

Calls POST /batch_search with {collection, queries: [...]}. Each query may carry either a text query (embedded server-side) or a raw vector. Returns one SearchResponse per query.

pub async fn batch_update_vectors( &self, collection: &str, updates: Vec<VectorUpdate>, ) -> Result<BatchUpdateReport>

Batch-update vector payloads (and optionally dense vectors).

Calls POST /batch_update with {collection, updates: [...]}.

pub async fn delete_by_filter( &self, collection: &str, filter: Value, ) -> Result<DeleteByFilterReport>

Delete every vector in a collection that matches a Qdrant-style metadata filter (phase13).

Calls POST /collections/{name}/vectors/delete_by_filter with {"filter": <filter>}. An empty filter is rejected by the server with 400 to prevent accidental full-collection wipes.

Response: {scanned, matched, deleted, results}.

Using the typed filter builder (recommended)

Use crate::models::QdrantFilter to build the filter with compile-time guidance. The server requires a Qdrant-style shape and returns 400 parse_error for wrong shapes (e.g. flat {key:value} or Qdrant-client-style {must:[{key,match:{value}}]}).

use vectorizer_sdk::models::{QdrantCondition, QdrantFilter};

let filter = QdrantFilter::must(vec![
    QdrantCondition::match_string("topic", "index"),
]);
client.delete_by_filter("my_col", serde_json::to_value(filter)?).await?;

See docs/users/api/API_REFERENCE.md § Filter shape for the full wire contract and a list of common mistakes.

pub async fn bulk_update_metadata( &self, collection: &str, filter: Value, patch: Value, ) -> Result<BulkUpdateReport>

Apply a JSON-merge-patch to the payload of every vector matching a filter (phase13).

Calls POST /collections/{name}/vectors/bulk_update_metadata with {"filter": <filter>, "patch": <patch>}. Patch is applied with RFC 7396 semantics: keys in patch overwrite existing payload values; null values remove keys.

Response: {scanned, matched, updated, results}.

Using the typed filter builder (recommended)

Use crate::models::QdrantFilter to build the filter with compile-time guidance. The server requires a Qdrant-style shape and returns 400 parse_error for wrong shapes.

use vectorizer_sdk::models::{QdrantCondition, QdrantFilter};

let filter = QdrantFilter::must(vec![
    QdrantCondition::match_string("status", "draft"),
]);
let patch = serde_json::json!({ "status": "published" });
client.bulk_update_metadata("my_col", serde_json::to_value(filter)?, patch).await?;

See docs/users/api/API_REFERENCE.md § Filter shape for the full wire contract and a list of common mistakes.

pub async fn copy_vectors( &self, src: &str, dst: &str, ids: &[String], ) -> Result<CopyReport>

Copy vectors from src to dst without re-embedding (phase13).

Unlike move_to_collection, the source vectors are NOT deleted. Calls POST /collections/{src}/vectors/copy with {"destination": dst, "ids": [...]}.

Per-id status: ok | missing_in_src | dst_insert_failed. Response: {src, dst, requested, copied, failed, results}.

pub async fn set_vector_expiry( &self, collection: &str, vector_id: &str, expires_at: Option<i64>, ) -> Result<()>

Set or clear a per-vector expiry timestamp (phase13).

Calls PATCH /collections/{name}/vectors/{id}/expiry with {"expires_at": <unix_ms>}. Pass None to clear an existing expiry. The timestamp is stored as __expires_at inside the vector payload and is read by the per-collection TTL reaper.

pub async fn embed_text( &self, text: &str, model: Option<&str>, ) -> Result<EmbeddingResponse>

Generate an embedding for text using either the supplied model name or the server default.

impl VectorizerClient

pub fn base_url(&self) -> &str

Get the base URL the client is configured against.

pub fn new(config: ClientConfig) -> Result<Self>

Create a new client with the given configuration.

pub fn new_default() -> Result<Self>

Create a new client with default configuration.

pub fn new_with_url(base_url: &str) -> Result<Self>

Create a client with a custom base URL.

pub fn new_with_api_key(base_url: &str, api_key: &str) -> Result<Self>

Create a client with a custom base URL + API key.

pub fn from_connection_string( connection_string: &str, api_key: Option<&str>, ) -> Result<Self>

Create a client from a full connection string (http(s)://host[:port] or umicp://host[:port]).

pub fn protocol(&self) -> Protocol

Returns the protocol the client is currently using.

pub async fn with_master<F, Fut, T>(&self, callback: F) -> Result<T>

where F: FnOnce(VectorizerClient) -> Fut, Fut: Future<Output = Result<T>>,

Execute a callback with master transport for read-your-writes scenarios. All operations within the callback are routed to master.

pub fn with_transport( transport: Arc<dyn Transport>, base_url: impl Into<String>, ) -> Self

Construct a VectorizerClient directly from a custom Transport implementation. Test-only / advanced use.

The dispatcher fields (master_transport, replica_transports, is_replica_mode) are all left empty — the client behaves as a single-transport instance. Used by mock-based tests to swap the real HTTP backend out for an in-memory one without touching the per-surface modules.

This entry point is the RPC-readiness regression guard (phase 4 task 2.4): if any per-surface module accidentally hard-codes HttpTransport or reqwest::Client, the MockTransport integration test in tests/mock_transport_regression.rs stops compiling. The same Transport trait the crate::rpc backend will plug into from phase6_sdk-rust-rpc is what mocks ride here.