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

> Explore VelesDB SDKs for Python, TypeScript, and mobile to build powerful vector search applications. Discover unified Rust core for server, web, and mobile.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: tutorial
- Published: 2026-02-28

---

**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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/sdks/typescript/src/client.ts) that supports two interchangeable backends:

- **WASM Backend** ([`sdks/typescript/src/backends/wasm.ts`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/lib.rs), this SDK compiles to platform-specific targets (`aarch64-apple-ios`, `aarch64-linux-android`) and produces [`VelesDB.swift`](https://github.com/cyberlife-coder/velesdb/blob/main/VelesDB.swift) and [`VelesDB.kt`](https://github.com/cyberlife-coder/velesdb/blob/main/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

```python
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)

```typescript
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)

```typescript
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

```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

```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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/sdks/typescript/src/client.ts) implements the high-level `VelesDB` class with backend abstraction.
- **WASM Backend Loader**: [`sdks/typescript/src/backends/wasm.ts`](https://github.com/cyberlife-coder/velesdb/blob/main/sdks/typescript/src/backends/wasm.ts) handles WebAssembly module instantiation.
- **REST Backend Client**: [`sdks/typescript/src/backends/rest.ts`](https://github.com/cyberlife-coder/velesdb/blob/main/sdks/typescript/src/backends/rest.ts) manages HTTP communication with the server.
- **Mobile Binding Generator**: [`crates/velesdb-mobile/src/lib.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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.