vdb

VDB vector database bindings for Kit — store and search high-dimensional vector embeddings

Files

Dependencies

No Kit package dependencies.

No system library installation is required. VDB is a header-only C library vendored in c/vdb.h.

Installation

kit add gitlab.com/kit-lang/packages/kit-vdb.git

Usage

import Kit.VDB as VDB

main = fn(-env) =>
  # Create a 3-dimensional database using cosine similarity
  db = VDB.create 3 VDB.cosine |> Result.unwrap

  # Add vectors with string identifiers
  VDB.add db [1.0, 0.0, 0.0] "x-axis" |> Result.unwrap
  VDB.add db [0.0, 1.0, 0.0] "y-axis" |> Result.unwrap
  VDB.add db [0.0, 0.0, 1.0] "z-axis" |> Result.unwrap
  VDB.add db [0.9, 0.1, 0.0] "near-x" |> Result.unwrap
  VDB.add db [0.5, 0.5, 0.0] "diagonal" |> Result.unwrap

  println "Database has ${show (VDB.count db)} vectors"

  # Search for the 3 nearest neighbors to a query vector
  results = VDB.search db [1.0, 0.0, 0.0] 3 |> Result.unwrap
  List.fold print-result no-op results

  # Save to disk and reload later
  VDB.save db "vectors.vdb" |> Result.unwrap
  loaded = VDB.load "vectors.vdb" |> Result.unwrap
  println "Loaded ${show (VDB.count loaded)} vectors from disk"

  VDB.destroy loaded
  VDB.destroy db

print-result = fn(-acc, r) =>
  println "  ${r.id} (distance: ${show r.distance})"

main

Distance Metrics

API Summary

Error Handling

All fallible operations return Result with typed VDBError variants:

match VDB.create 3 VDB.cosine
  | Ok db -> println "Created database"
  | Err (VDBInvalidDimensions {message}) -> println "Bad dims: ${message}"
  | Err e -> println "Error: ${show e}"

Variants: VDBNullPointer, VDBInvalidDimensions, VDBOutOfMemory, VDBNotFound, VDBInvalidIndex, VDBIOError.

Development

Running Examples

Run examples with the interpreter:

kit run --allow=ffi --allow=file examples/basic.kit

Compile examples to a native binary:

kit build --allow=ffi --allow=file examples/basic.kit -o basic && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/vdb/, making it available for import as Kit.VDB in other projects.

License

This package is released under the MIT License - see LICENSE for details.

VDB is released under the Apache License 2.0.

Exported Functions & Types

cosine

Cosine similarity metric (measures angle between vectors).

Int

euclidean

Euclidean distance metric (measures straight-line distance).

Int

dot-product

Dot product metric (measures projection of one vector onto another).

Int

VDBError

Error type for VDB operations.

Type

create

Create a new vector database with the given number of dimensions and distance metric. Use VDB.cosine, VDB.euclidean, or VDB.dot-product for the metric.

PositiveInt -> Int -> Result Ptr VDBError

db = VDB.create 128 VDB.cosine |> Result.unwrap

destroy

Destroy a database and free its memory.

Ptr -> Unit

count

Return the number of vectors in the database.

Ptr -> Int

dimensions

Return the dimensionality of the database.

Ptr -> Int

add

Add a vector to the database with an optional string identifier. The vector is a list of floats whose length must match the database dimensions.

Ptr -> List Float -> String -> Result Unit VDBError

VDB.add db [0.1, 0.2, 0.3] "my-vector" |> Result.unwrap

remove

Remove a vector from the database by index.

Ptr -> NonNegativeInt -> Result Unit VDBError

get-id

Get the string identifier of a vector at the given index.

Ptr -> NonNegativeInt -> String

get-data

Get the raw vector data at the given index as a comma-separated string.

Ptr -> NonNegativeInt -> String

search

Search for the k nearest neighbors to a query vector. Returns a list of records with index, distance, and id fields.

Ptr -> List Float -> PositiveInt -> Result List VDBError

results = VDB.search db [1.0, 0.0, 0.0] 5 |> Result.unwrap
results |> List.map fn(r) => println "${r.id} (distance: ${show r.distance})"

save

Save the database to a binary file.

Ptr -> NonEmptyString -> Result Unit VDBError

VDB.save db "vectors.vdb" |> Result.unwrap

load

Load a database from a binary file.

NonEmptyString -> Result Ptr VDBError

db = VDB.load "vectors.vdb" |> Result.unwrap