VelesDB SDKs for Python, TypeScript, and Mobile: A Complete Technical Guide

VelesDB provides three official SDKs—velesdb-python for Python 3.9+, @wiscale/velesdb-sdk for TypeScript and JavaScript with interchangeable WASM and REST backends, and velesdb-mobile with UniFFI-generated Swift and Kotlin bindings—all wrapping a single Rust core to deliver identical vector search semantics across server, web, and mobile environments.

The cyberlife-coder/velesdb repository distributes a unified vector database engine through language-specific VelesDB SDKs. Each SDK compiles the shared velesdb-core Rust library for its target platform, ensuring microsecond latency and consistent HNSW index behavior whether you are building Python data pipelines, browser-based applications, or on-device mobile experiences.

VelesDB SDK Architecture and Language Bindings

Python SDK: Native CPython Extensions via PyO3

The velesdb-python crate compiles the Rust core into a native CPython extension using PyO3 bindings. Located in crates/velesdb-python/src/lib.rs, this SDK exposes the Database and Collection classes directly to Python 3.9+ environments. When you execute import velesdb, you load a compiled shared object (.so or .pyd) that invokes the core's Rust API without network overhead, enabling NumPy and pandas interoperability with bare-metal performance.

TypeScript SDK: Dual Backend Architecture

The @wiscale/velesdb-sdk package provides a unified client abstraction in sdks/typescript/src/client.ts that supports two interchangeable backends:

• WASM Backend (sdks/typescript/src/backends/wasm.ts): Compiles the Rust core to WebAssembly via the velesdb-wasm crate, running entirely within the browser or Node.js without network calls.
• REST Backend (sdks/typescript/src/backends/rest.ts): Forwards JSON API calls to a remote velesdb-server over HTTP.

This dual-mode architecture allows the same TypeScript code to run locally in browser environments or connect to managed server instances.

Mobile SDK: UniFFI-Generated Swift and Kotlin Bindings

The velesdb-mobile crate targets iOS and Android through UniFFI, which auto-generates native language bindings from the Rust library. Located in crates/velesdb-mobile/src/lib.rs, this SDK compiles to platform-specific targets (aarch64-apple-ios, aarch64-linux-android) and produces VelesDB.swift and VelesDB.kt files. The generated code marshals data using zero-copy buffers, preserving microsecond search latency on edge devices while exposing idiomatic APIs for each mobile platform.

VelesDB SDK Code Examples by Platform

Python Vector Search Implementation

import velesdb
import numpy as np

# Open (or create) a database file

db = velesdb.Database("./my_vectors")

# Create a collection for 384-dim BERT embeddings

col = db.create_collection("documents", dimension=384, metric="cosine")

# Insert vectors using NumPy arrays

emb = np.random.rand(384).astype("float32")
col.upsert({"id": 1, "vector": emb.tolist(), "payload": {"title": "Hello"}})

# Execute vector search

results = col.search(vector=emb.tolist(), top_k=5)
for r in results:
    print(r["id"], r["score"])

TypeScript WASM Backend (Browser/Node.js)

import { VelesDB } from "@wiscale/velesdb-sdk";

async function run() {
  // Initialize with WASM backend for local execution
  const db = new VelesDB({ backend: "wasm" });
  await db.init();

  await db.createCollection("docs", { dimension: 768, metric: "cosine" });
  
  const vec = new Float32Array(768).fill(0.1);
  await db.insert("docs", { id: "doc-1", vector: vec, payload: { title: "Hello" } });

  const results = await db.search("docs", vec, { k: 5 });
  console.log(results);
}
run();

TypeScript REST Backend (Server Client)

import { VelesDB } from "@wiscale/velesdb-sdk";

const db = new VelesDB({
  backend: "rest",
  url: "http://localhost:8080",
});
await db.init();

await db.createCollection("products", { dimension: 384 });
await db.insert("products", { id: "p1", vector: new Float32Array(384).fill(0.2) });

const hits = await db.search("products", new Float32Array(384).fill(0.2), { k: 10 });
console.log(hits);

iOS Development with Swift

import VelesDB

let db = try VelesDatabase.open(path: documentsPath + "/velesdb")

// Create collection with SQ8 compression for mobile optimization
try db.createCollectionWithStorage(
    name: "embeddings",
    dimension: 384,
    metric: .cosine,
    storageMode: .sq8
)

let point = VelesPoint(
    id: 1,
    vector: embedding,
    payload: "{\"title\":\"Hello\"}"
)
try db.getCollection(name: "embeddings")?.upsert(point: point)

let results = try db.getCollection(name: "embeddings")?.search(vector: queryEmbedding, limit: 5)
results?.forEach { print("ID:", $0.id, "Score:", $0.score) }

Android Development with Kotlin

import com.velesdb.mobile.*

suspend fun demo(context: Context) {
    val db = VelesDatabase.open("${context.filesDir}/velesdb")
    
    // Binary quantization for ultra-low memory footprint
    db.createCollectionWithStorage("embeddings", 384u, DistanceMetric.COSINE, StorageMode.BINARY)
    
    val point = VelesPoint(
        id = 1uL,
        vector = embedding,
        payload = """{"title":"Hello"}"""
    )
    val coll = db.getCollection("embeddings") ?: error("Missing collection")
    coll.upsert(point)
    
    val results = withContext(Dispatchers.IO) {
        coll.search(queryEmbedding, 5u)
    }
    results.forEach { println("ID=${it.id} score=${it.score}") }
}

Key Source Files and Implementation Paths

Understanding the VelesDB SDK architecture requires examining specific source locations in the cyberlife-coder/velesdb repository:

• Python SDK Entry Point: crates/velesdb-python/src/lib.rs contains the PyO3 binding definitions that expose Rust structs to Python.
• TypeScript Client Core: sdks/typescript/src/client.ts implements the high-level VelesDB class with backend abstraction.
• WASM Backend Loader: sdks/typescript/src/backends/wasm.ts handles WebAssembly module instantiation.
• REST Backend Client: sdks/typescript/src/backends/rest.ts manages HTTP communication with the server.
• Mobile Binding Generator: crates/velesdb-mobile/src/lib.rs defines the Rust interface used by UniFFI to generate Swift and Kotlin headers.

Summary

• VelesDB SDKs share a single Rust core (velesdb-core) that implements HNSW vector indexing, quantization, and graph search, ensuring consistent behavior across all platforms.
• The Python SDK (velesdb-python) uses PyO3 to compile native extensions for Python 3.9+, offering direct NumPy integration without network overhead.
• The TypeScript SDK (@wiscale/velesdb-sdk) provides dual backends: a WASM backend for browser/Node.js local execution and a REST backend for remote server communication.
• The Mobile SDK (velesdb-mobile) leverages UniFFI to generate zero-overhead Swift and Kotlin bindings for iOS and Android, supporting storage modes like SQ8 and binary quantization for edge deployment.
• All SDKs maintain identical vector search semantics and microsecond latency characteristics regardless of the host language or platform.

Frequently Asked Questions

What Python versions are supported by the VelesDB Python SDK?

The velesdb-python crate officially supports Python 3.9 and later. The PyO3 bindings compile the Rust core into a CPython extension that loads as a native shared object, allowing direct integration with NumPy arrays and pandas DataFrames without serialization overhead.

Can the TypeScript SDK run without a network connection?

Yes. The @wiscale/velesdb-sdk package includes a WASM backend that compiles the Rust core to WebAssembly and executes locally within the browser or Node.js runtime. This backend, implemented in sdks/typescript/src/backends/wasm.ts, requires no network connection and provides the same vector search performance as the native Rust core.

How does the Mobile SDK handle memory constraints on devices?

The velesdb-mobile crate supports aggressive quantization strategies through UniFFI-generated bindings. Developers can specify storage modes like SQ8 (8-bit scalar quantization) or BINARY (binary quantization) when creating collections in Swift or Kotlin, significantly reducing memory footprint while maintaining search accuracy on iOS and Android devices.

Are the SDK APIs consistent across Python, TypeScript, and mobile platforms?

While each VelesDB SDK exposes language-idiomatic APIs, they all wrap the identical velesdb-core Rust implementation. This guarantees that vector search semantics, HNSW index behavior, distance metrics (cosine, Euclidean), and metadata handling remain consistent whether you are using the Python module, TypeScript client, or Swift/Kotlin bindings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}