usearch 2.0.2 → 2.1.1

package/.github/workflows/Dockerfile.libs

@@ -0,0 +1,34 @@
+FROM ubuntu:22.04
+ENV DEBIAN_FRONTEND=noninteractive
+
+ENV user_name="runner"
+ARG TARGETPLATFORM
+ARG docker_ip
+ARG user_pass
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends cmake g++-12 build-essential libjemalloc-dev golang openssh-client sshpass && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY . .
+
+RUN cd golang && make -C ../c libusearch_c.so && \
+    mv ../c/libusearch_c.so libusearch.a && cp ../c/usearch.h usearch.h && \
+    go test -v && cd ..
+
+RUN if [ "$TARGETPLATFORM" = "linux/amd64" ]; then \
+        export arch="amd"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm64" ]; then \
+        export arch="arm"; \
+    fi && \
+    version=$(cat VERSION) && \
+    mkdir -p usearch_linux_"$arch"_"$version"/DEBIAN && \
+    touch usearch_linux_"$arch"_"$version"/DEBIAN/control && \
+    mkdir -p usearch_linux_"$arch"_"$version"/usr/local/lib && \
+    mkdir usearch_linux_"$arch"_"$version"/usr/local/include && \
+    cp c/usearch.h usearch_linux_"$arch"_"$version"/usr/local/include/ && \
+    cp golang/libusearch.a usearch_linux_"$arch"_"$version"/usr/local/lib/ && \
+    echo "Package: usearch\nVersion: $version\nMaintainer: Ashot Vardanian\nArchitecture: "$arch"\nDescription: Faster & Smaller Single-File Search Engine for Vectors & Texts" > usearch_linux_"$arch"_"$version"/DEBIAN/control && \
+    dpkg-deb --build usearch_linux_"$arch"_"$version" && \
+    sshpass -p "$user_pass" scp -o StrictHostKeyChecking=no usearch_linux_"$arch"_"$version".deb "$user_name"@"$docker_ip":/home/$user_name/work/usearch/usearch/

package/.github/workflows/prerelease.yml

@@ -219,6 +219,33 @@ jobs:
         shell: bash
         working-directory: ${{ github.workspace }}/csharp/
 
+  test_golang:
+    name: Test Golang
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+        ref: 'main-dev'
+    - run: git submodule update --init --recursive
+
+    - name: Prepare environment
+      run: |
+        sudo apt update && 
+        sudo apt install -y cmake g++-12 build-essential libjemalloc-dev
+          
+    - name: Build library
+      run: |
+        cd golang && make -C ../c libusearch_c.so
+        sudo mv ../c/libusearch_c.so /usr/local/lib/libusearch.a
+        sudo mv ../c/usearch.h /usr/local/include/usearch.h
+
+    - name: Run test
+      run: |
+        cd golang
+        go test -v
+        
+
   build_docker:
     name: Test Docker Image
     runs-on: ubuntu-latest

package/.github/workflows/release.yml

@@ -14,6 +14,7 @@ permissions:
   contents: write
   pages: write
   id-token: write
+  packages: write
 
 jobs:
 
@@ -52,10 +53,172 @@ jobs:
           force: True
 
 
+  create_linux_deb_package:
+    name: Create Debian Package for ${{ matrix.arch }}
+    runs-on: ubuntu-latest
+    needs: versioning
+    strategy:
+      matrix:
+        arch: ["linux/amd64", "linux/arm64"]
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+        ref: 'main'
+    - run: git submodule update --init --recursive
+
+    - name: Setup QEMU
+      uses: docker/setup-qemu-action@v2
+
+    - name: Setup Docker
+      uses: docker/setup-buildx-action@v2
+
+    - name: Get Docker daemon IP
+      id: dockerip
+      run: |
+        docker_ip=$(ip addr show docker0 | grep -Po 'inet \K[\d.]+') && \
+        echo "docker_ip=$docker_ip" >> "$GITHUB_OUTPUT"
+        
+    - name: Set runner user password
+      id: userpass
+      run: |
+        user_pass="1122"
+        echo "runner:$user_pass" | sudo chpasswd
+        echo "user_pass=$user_pass" >> "$GITHUB_OUTPUT"
+          
+    - name: Build library
+      run: |
+        docker buildx create --use
+        docker buildx build \
+        --platform ${{ matrix.arch }} \
+        --build-arg docker_ip=${{ steps.dockerip.outputs.docker_ip }} \
+        --build-arg user_pass=${{ steps.userpass.outputs.user_pass }} \
+        --file .github/workflows/Dockerfile.libs \
+        --tag unum/ustore-deps:latest \
+        --load .
+    - name: Clear Docker buildx cache
+      run: docker buildx prune --all --force
+
+    - name: Upload archive
+      uses: xresloader/upload-to-github-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        file: "*.deb"
+        update_latest_release: true
+
+
+  create_windows_dll_library:
+    name: Create Dll Library for Windows ${{ matrix.arch }}
+    runs-on: windows-latest
+    needs: versioning
+    strategy:
+      matrix:
+        arch: [x64, x86]
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+        ref: 'main'
+    - run: git submodule update --init --recursive
+    
+    - name: Setup Cmake
+      uses: jwlawson/actions-setup-cmake@v1.13
+    
+    - uses: actions/setup-go@v4
+      with:
+        go-version: '^1.19.0'
+
+    - name: Setup Mingw
+      uses: egor-tensin/setup-mingw@v2
+      with:
+        platform: ${{ matrix.arch }}
+
+    - name: Get version
+      id: set_version
+      shell: bash
+      run: |
+        version=$(cat VERSION)
+        echo "version=$version" >> $GITHUB_OUTPUT
+        
+    - name: Build library
+      run: |
+        cd c/ && g++ -std=c++11 -o libusearch.dll -O3 lib.cpp -I.  -I ../include/  -I ../fp16/include/ -shared && cd ..
+        cp c/libusearch.dll golang/libusearch.dll && cp c/usearch.h golang/usearch.h
+    
+    - name: Golang test
+      run: |
+        cd golang/ && go test -v
+      if: ${{ matrix.arch == 'x64' }}
+
+    - name: Compress library
+      run: |
+        cd golang/
+        tar -cvf usearch_windows_${{ matrix.arch }}_${{ steps.set_version.outputs.version }}.tar .\libusearch.dll .\usearch.h
+
+    - name: Upload archive
+      uses: xresloader/upload-to-github-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        file: "golang/usearch_windows_${{ matrix.arch }}_${{ steps.set_version.outputs.version }}.tar"
+        update_latest_release: true
+
+
+  create_macos_library:
+    name: Create Library for MacOS ${{ matrix.arch }}
+    runs-on: macOS-latest
+    needs: versioning
+    strategy:
+      matrix:
+        arch: [arm64, x86_64]
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+        ref: 'main'
+    - run: git submodule update --init --recursive
+    
+    - uses: actions/setup-go@v4
+      with:
+        go-version: '^1.21.0'
+
+    - name: Get version
+      id: version
+      run: |
+        version=$(cat VERSION)
+        echo "version=$version" >> $GITHUB_OUTPUT
+
+    - name: Build library
+      run: |
+        cd c/ && clang++ -std=c++11 -o libusearch.so -O3 lib.cpp -I.  -I ../include/  -I ../fp16/include/ -shared -target ${{ matrix.arch }}-apple-macos11 && cd ..
+        cp c/usearch.h golang/
+        cp c/libusearch.so golang/libusearch.so
+
+    - name: Golang test
+      run: |
+        cd golang/
+        go test -v
+      if: ${{ matrix.arch == 'x86_64' }}
+
+    - name: Compress library
+      run: |
+        cd golang/
+        zip -r usearch_macOS_${{ matrix.arch }}_${{ steps.version.outputs.version }}.zip libusearch.so usearch.h 
+
+    - name: Upload archive
+      uses: xresloader/upload-to-github-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        file: "golang/*.zip"
+        update_latest_release: true
+
+
   publish_hashes:
     name: Add hashes to release notes
     runs-on: ubuntu-latest
-    needs: versioning
+    needs: [versioning, create_linux_deb_package, create_windows_dll_library, create_macos_library]
     steps:
     - name: Get last release ID
       id: last_release
@@ -319,11 +482,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: [build_csharp]
     env:
+      SOLUTION: ${{ github.workspace }}/csharp
       USEARCH_LIBS: ${{ github.workspace }}/csharp/lib
-      NUGET_DIR: ${{ github.workspace }}/csharp/packages
+      NUGET_PACKAGES: ${{ github.workspace }}/csharp/packages
       # NUGET_SOURCE: https://apiint.nugettest.org/v3/index.json
       NUGET_SOURCE: https://api.nuget.org/v3/index.json
-      SOLUTION_DIR: ${{ github.workspace }}/csharp
+      GITHUB_PACKAGES_SOURCE: https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json
     steps:
       - uses: actions/checkout@v3
       - run: git submodule update --init --recursive
@@ -342,12 +506,17 @@ jobs:
       - name: Pack project
         run: |
           VERSION_CONTENT=$(< VERSION)
-          dotnet pack "${{ env.SOLUTION_DIR }}" -c Release -p:Version="$VERSION_CONTENT" --output ${{ env.NUGET_DIR }}
+          dotnet pack "${{ env.SOLUTION }}" -c Release -p:Version="$VERSION_CONTENT" --output ${{ env.NUGET_PACKAGES }}
         working-directory: ${{ github.workspace }}
 
-      - name: Publish NuGet packages
-        run: |
-          dotnet nuget push "${{  env.NUGET_DIR }}/*.nupkg" --api-key "${{ secrets.NUGET_API }}" --source "${{ env.NUGET_SOURCE }}"
+      - name: Publish to NuGet
+        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg" --api-key "${{ secrets.NUGET_API }}" --source "${{ env.NUGET_SOURCE }}" --skip-duplicate
+
+      - name: Prepare publish to GitHub Registry
+        run: dotnet nuget add source --username ${{ github.repository_owner }} --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "${{ env.GITHUB_PACKAGES_SOURCE }}"
+
+      - name: Publish to GitHub Registry
+        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg"  --api-key "${{ secrets.GITHUB_TOKEN }}" --source "github" --skip-duplicate
 
   build_docs:
     name: Build Docs

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "2.0.2"
+version = "2.1.1"
 authors = ["Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '2.0.2'
+    version = '2.1.1'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/csharp/README.md

@@ -40,7 +40,7 @@ index.Save("index.usearch")
 using var indexLoaded = new USearchIndex("index.usearch");
 
 // Or view from disk without loading in memory
-// using var indexLoaded = new USearchIndex("index.usearch", view: True);
+// using var indexLoaded = new USearchIndex("index.usearch", view: true);
 
 Trace.Assert(indexLoaded.Size() == 1);
 Trace.Assert(indexLoaded.Dimensions() == 3);

package/csharp/nuget/nuget-package.props

@@ -15,14 +15,14 @@
 
     <PackageIcon>unum.png</PackageIcon>
     <PackageIconUrl>unum.png</PackageIconUrl>
-    <PackageReadmeFile>NUGET.md</PackageReadmeFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
     <None Include="$(NativeLibDir)runtimes\**\*.*" Pack="true" PackagePath="runtimes" />
     <None Include="$(RepoRoot)LICENSE" Pack="true" PackagePath=""/>
     <None Include="$(RepoRoot)assets\unum.png" Pack="true" PackagePath=""/>
-    <None Include="$(CSharpDir)nuget\NUGET.md" Pack="true" PackagePath=""/>
+    <None Include="$(RepoRoot)README.md" Pack="true" PackagePath=""/>
   </ItemGroup>
 
   <!-- Package validation https://learn.microsoft.com/en-us/dotnet/fundamentals/package-validation/overview?WT.mc_id=DT-MVP-5003978 -->

package/golang/README.md

@@ -2,51 +2,94 @@
 
 ## Installation
 
-```golang
-import (
-	"github.com/unum-cloud/usearch/golang-go"
-)
+### Linux
+
+Download and install from the Debian package from the latest release.
+Substitute `<release_tag>`, `<arch>`, and `<usearch_version>` with your settings.
+
+```
+wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_linux_<arch>_<usearch_version>.deb
+dpkg -i usearch_<arch>_<usearch_version>.deb
+```
+
+### Windows
+
+Run a `winlibinstaller.bat` script from the main repository in the folder where you will run `go run`.
+That will install the USearch library and include in the same folder` where the script was run.
+
+```
+.\usearch\winlibinstaller.bat
+```
+
+### MacOS
+
+Download and unpack a zip archive from the latest release.
+Move the USearch library and the include file to their respective folders.
+```
+wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_macOS_<arch>_<usearch_version>.zip
+unzip usearch_macOS_<arch>_<usearch_version>.zip
+sudo mv libusearch.so /usr/local/lib && sudo mv usearch.h /usr/local/include
+
 ```
 
 ## Quickstart
 
-```golang
-package main
+1. Create a `go.mod` file:
 
-import (
-	"fmt"
-	"github.com/unum-cloud/usearch/golang-go"
-)
+	```
+	module usearch_example
 
-func main() {
-	dim := uint(128)
-	conf := DefaultConfig(dim)
-	ind, err := NewIndex(conf)
-	if err != nil {
-		panic("Failed to construct the index: %s", err)
-	}
-	defer ind.Destroy()
+	go <go_version>
+	```
 
-	err = ind.Reserve(100)
-	if err != nil {
-		panic("Failed to reserve capacity: %s", err)
-	}
+2. Create an `example.go`:
 
-	vec := make([]float32, dim)
-	vec[0] = 40.0
-	vec[1] = 2.0
+	```golang
+	package main
 
-	err = ind.Add(42, vec)
-	if err != nil {
-		panic("Failed to insert: %s", err)
-	}
+	import (
+		"fmt"
+		usearch "github.com/unum-cloud/usearch/golang"
+	)
 
-	keys, distances, err := ind.Search(vec, 10)
-	if err != nil {
-		panic("Failed to search: %s", err)
-	}
-	if keys[0] != 42 || distances[0] != 0.0 {
-		panic("Expected result 42 with distance 0, got key %d with distance %f", keys[0], distances[0])
+	func main() {
+
+		// Create Index
+		vector_size := 3
+		vectors_count := 100
+		conf := usearch.DefaultConfig(uint(vector_size))
+		index,err := usearch.NewIndex(conf)
+		if err != nil {
+			panic("Failed to create Index")
+		}
+		defer index.Destroy()
+		
+		// Add to Index
+		err = index.Reserve(uint(vectors_count))
+		for i := 0; i < vectors_count; i++ {
+			err = index.Add(usearch.Key(i), []float32{float32(i), float32(i+1), float32(i+2)})
+			if err != nil {
+				panic("Failed to add")
+			}
+		}
+
+		// Search
+		keys, distances, err := index.Search([]float32{0.0, 1.0, 2.0}, 3)
+		if err != nil {
+			panic("Failed to search")
+		}
+		fmt.Println(keys, distances)
 	}
-}
-```
+	```
+
+3. Get USearch:
+
+	```
+	go get github.com/unum-cloud/usearch/golang
+	```
+
+4. Run:
+
+	```
+	go run example.go
+	```

package/golang/lib.go

@@ -6,9 +6,8 @@ import (
 )
 
 /*
-#cgo CFLAGS: -I${SRCDIR}/../c/
-#cgo LDFLAGS: -L${SRCDIR}/. -Wl,-rpath,\$ORIGIN/ -lusearch_c
-#include <usearch.h>
+#cgo LDFLAGS: -L. -lusearch
+#include "usearch.h"
 #include <stdlib.h>
 */
 import "C"
@@ -91,6 +90,8 @@ type IndexConfig struct {
 	ExpansionAdd uint
 	// The @b optional expansion factor used for index construction during search operations.
 	ExpansionSearch uint
+	// The @b optional multi flag.
+	Multi bool
 }
 
 func DefaultConfig(dimensions uint) IndexConfig {
@@ -101,6 +102,7 @@ func DefaultConfig(dimensions uint) IndexConfig {
 	c.Connectivity = 0
 	c.ExpansionAdd = 0
 	c.ExpansionSearch = 0
+	c.Multi = false
 	return c
 }
 
@@ -114,16 +116,18 @@ func NewIndex(conf IndexConfig) (index *Index, err error) {
 	index = &Index{config: conf}
 
 	conf = index.config
-	dimensions := C.ulong(conf.Dimensions)
-	connectivity := C.ulong(conf.Connectivity)
-	expansion_add := C.ulong(conf.ExpansionAdd)
-	expansion_search := C.ulong(conf.ExpansionSearch)
+	dimensions := C.size_t(conf.Dimensions)
+	connectivity := C.size_t(conf.Connectivity)
+	expansion_add := C.size_t(conf.ExpansionAdd)
+	expansion_search := C.size_t(conf.ExpansionSearch)
+	multi := C.bool(conf.Multi)
 
 	options := C.struct_usearch_init_options_t{}
 	options.dimensions = dimensions
 	options.connectivity = connectivity
 	options.expansion_add = expansion_add
 	options.expansion_search = expansion_search
+	options.multi = multi
 
 	// Map the metric kind to a C enum
 	switch conf.Metric {
@@ -281,21 +285,21 @@ func (index *Index) Contains(key Key) (found bool, err error) {
 	return found, nil
 }
 
-func (index *Index) Get(key Key) (vector []float32, err error) {
+func (index *Index) Get(key Key, count uint) (vectors []float32, err error) {
 	if index.opaque_handle == nil {
 		panic("Index is uninitialized")
 	}
 
-	vector = make([]float32, index.config.Dimensions)
+	vectors = make([]float32, index.config.Dimensions * count)
 	var errorMessage *C.char
-	found := bool(C.usearch_get((C.usearch_index_t)(unsafe.Pointer(index.opaque_handle)), (C.usearch_key_t)(key), unsafe.Pointer(&vector[0]), C.usearch_scalar_f32_k, (*C.usearch_error_t)(&errorMessage)))
+	found := uint(C.usearch_get((C.usearch_index_t)(unsafe.Pointer(index.opaque_handle)), (C.usearch_key_t)(key), (C.size_t)(count), unsafe.Pointer(&vectors[0]), C.usearch_scalar_f32_k, (*C.usearch_error_t)(&errorMessage)))
 	if errorMessage != nil {
 		return nil, errors.New(C.GoString(errorMessage))
 	}
-	if !found {
+	if found == 0 {
 		return nil, nil
 	}
-	return vector, nil
+	return vectors, nil
 }
 
 // Performs k-Approximate Nearest Neighbors Search for closest vectors to query.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.0.2",
+    "version": "2.1.1",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian",
     "license": "Apache 2.0",

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.0.2"
+version="2.1.1"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"

package/winlibinstaller.bat

@@ -0,0 +1,42 @@
+@echo off
+
+rem Get latest release tag
+set "repo_owner=unum-cloud"
+set "repo_name=usearch"
+
+rem Get the latest tag without quotes
+for /f "delims=" %%i in ('curl -s https://api.github.com/repos/%repo_owner%/%repo_name%/releases/latest ^| findstr "tag_name"') do (
+    for /f "tokens=2 delims=:, " %%a in ("%%i") do (
+        set "latest_tag=%%~a"
+    )
+)
+
+rem Get Windows architecture
+for /f "tokens=2 delims= " %%a in ('wmic OS get OSArchitecture ^| find "64"') do set "arch=x64"
+if "%arch%"=="" set "arch=x86"
+
+echo Split library version from release version!
+timeout /t 1
+rem Split the first 'v' from the version number.
+for /f "tokens=1 delims=v" %%a in ('echo %latest_tag%') do (
+    set lib_version=%%a
+)
+
+echo Download usearch library archive!
+rem Download the file.
+timeout /t 2
+curl -LO https://github.com/%repo_owner%/%repo_name%/releases/download/%latest_tag%/usearch_windows_%arch%_%lib_version%.tar
+echo Download is complete!
+
+echo Extract archive!
+rem Extract archive.
+timeout /t 1
+tar -xf usearch_windows_%arch%_%lib_version%.tar
+echo Extract is complete!
+
+rem Remove the archive.
+del usearch_windows_%arch%_%lib_version%.tar
+
+echo Extraction complete and downloaded .tar file removed.
+timeout /t 1
+exit /b

package/csharp/nuget/NUGET.md

@@ -1,11 +0,0 @@
-**Cloud.Unum.USearch** is a wrapper for the USearch vector search engine, offering fast searches, multiple metrics, and features like SIMD-optimized metrics.
-
-**Supported metrics**: Euclidean, Angular, Jaccard, Hamming, Haversine, User-Defined Metrics
-
-**Platforms**: Linux, MacOS, Windows
-
-# Getting Started ⚡
-
-- [Quickstart](https://github.com/unum-cloud/usearch/blob/main/csharp/README.md)
-- Join the [Discord community](https://discord.gg/A6wxt6dS9j)
-- Check out the [GitHub repository](https://github.com/unum-cloud/usearch)