SDKs Overview

brinicle provides official SDK clients for communicating with the brinicle HTTP server. Each SDK wraps the REST API and binary protocols into a clean, idiomatic interface for its respective language.

Available SDKs

Language	Package	Registry	Install
PHP	`bicardinal/brinicle-php`	Composer	`composer require bicardinal/brinicle-php`
Laravel	`bicardinal/brinicle-laravel`	Composer	`composer require bicardinal/brinicle-laravel`
TypeScript	`@bicardinal/brinicle`	npm	`npm install @bicardinal/brinicle`
Python	`brinicle-client`	PyPI	`pip install brinicle-client`
Go	`github.com/bicardinal/brinicle-go`	Go Modules	`go get github.com/bicardinal/brinicle-go`

Common Pattern

All SDKs follow the same general pattern, mirroring the HTTP API:

Create a client — Connect to the brinicle server
Create an index — Set up a new vector index with dimensions and parameters
Initialize an ingest session — Start building, inserting, or upserting
Ingest data — Add vectors one at a time or in batches
Finalize — Complete the ingest and build the HNSW graph
Search — Query the index for nearest neighbors
Maintain — Delete, rebuild, and optimize as needed

Binary Protocols

The batch ingest and search operations use binary protocols for maximum performance:

Batch ingest: Each row is a 32-byte null-padded ASCII ID followed by dim * 4 bytes of float32 little-endian vector data
Search: The query vector is sent as dim * 4 bytes of float32 little-endian data

All SDKs handle the binary encoding internally, so you don’t need to worry about byte-level details.

Connection Configuration

All SDKs allow you to configure the server URL and connection timeout:

SDK	Default URL	Default Timeout
PHP	`http://localhost:1984`	30s
Laravel	via config/env	via config/env
TypeScript	`http://localhost:1984`	30s
Python	`http://localhost:1984`	30s
Go	`http://localhost:1984`	30s

Error Handling

All SDKs provide a consistent error hierarchy:

Error Type	HTTP Status	Description
Connection Error	—	Could not connect to the server
Validation Error	400	Invalid request parameters
Not Found Error	404	Index not found
Conflict Error	409	Index already exists
Server Error	5xx	Internal server error

Quick Comparison

Create Index

PHP
Laravel
TypeScript
Python
Go

use Bicardinal\Brinicle\BrinicleClient;

$client = new BrinicleClient('http://localhost:1984');
$client->createIndex('my_index', dim: 128);

use Bicardinal\BrinicleLaravel\Facades\Brinicle;

Brinicle::createIndex('my_index', dim: 128);

import { BrinicleClient } from '@bicardinal/brinicle';

const client = new BrinicleClient({ baseUrl: 'http://localhost:1984' });
await client.createIndex('my_index', 128);

from brinicle_client import BrinicleClient

client = BrinicleClient('http://localhost:1984')
client.create_index('my_index', dim=128)

client := brinicle.NewClient("http://localhost:1984")
client.CreateIndex(ctx, "my_index", 128, 0.10, nil)

Search

PHP
Laravel
TypeScript
Python
Go

$results = $client->search('my_index', [0.1, 0.2, 0.3], k: 5);

$results = Brinicle::search('my_index', [0.1, 0.2, 0.3], k: 5);

const results = await client.search('my_index', [0.1, 0.2, 0.3], 5);

results = client.search('my_index', [0.1, 0.2, 0.3], k=5)

results, err := client.Search(ctx, "my_index", []float32{0.1, 0.2, 0.3}, 5, 64)

​SDKs Overview

​Available SDKs

​Common Pattern

​Binary Protocols

​Connection Configuration

​Error Handling

​Quick Comparison

​Create Index

​Search