​
Installation

brinicle can be installed in multiple ways depending on your use case. The core library is available as a Python package, and a standalone HTTP server is available for deployment as a service.

​
Python Package (pip)

The simplest way to get started with brinicle is through pip. The package includes the C++ core with Python bindings, so no separate compilation step is needed for most platforms: 
pip install brinicle
Or install from source: 
git clone https://github.com/bicardinal/brinicle.git
cd brinicle
pip install -e .
This installs the core library which provides direct in-process access to the vector engine. You can use it directly in your Python applications without any server setup.

​
Requirements

  • Python 3.12.x

​
Runtime Dependencies

The Python package requires:
  • numpy — for vector operations and array handling
  • tokenizers — HuggingFace tokenizers library (for Item Search and Autocomplete engines)

​
Build from Source

If you need to build from source — for example, if pre-built wheels are not available for your platform — you can clone the repository and build manually: 
git clone https://github.com/bicardinal/brinicle.git
cd brinicle
bash build.sh
The build.sh script compiles the C++ core with pybind11 bindings and installs the package into your Python environment. It requires a C++20-compatible compiler (such as g++ 10+ or Clang 12+).

​
Build Dependencies

  • scikit-build-core >= 0.11
  • pybind11 >= 2.11
  • cmake >= 3.18
  • ninja
  • C++20 compiler with OpenMP support

​
HTTP Server (Docker)

For deploying brinicle as a standalone service, you can use Docker. The official Docker image includes the FastAPI server ready for production use: 
docker compose up -d
The default configuration runs the server on port 1984 with a 1GB memory limit. You can customize these settings in the docker-compose.yml file.

​
Manual Server Setup

Alternatively, you can install the server dependencies and run the FastAPI application directly: 
pip install brinicle[server]
uvicorn brinicle.ref.api:app --host 0.0.0.0 --port 1984
The brinicle[server] extra installs FastAPI, Uvicorn, Pydantic, and python-multipart — all the dependencies needed to run the HTTP server.

​
SDK Installation

If you prefer to use the HTTP server and communicate via an SDK client, install the appropriate package for your language:

​
PHP

composer require bicardinal/brinicle-php

​
Laravel

composer require bicardinal/brinicle-laravel

​
TypeScript / JavaScript

npm install @bicardinal/brinicle
# or
yarn add @bicardinal/brinicle
# or
pnpm add @bicardinal/brinicle

​
Python HTTP Client

pip install brinicle-client

​
Go

go get github.com/bicardinal/brinicle-go

​
Verifying Installation

After installing the core library, you can verify that brinicle is working correctly by running a simple test: 
import brinicle
import numpy as np

engine = brinicle.VectorEngine("test_index", dim=2)
engine.init(mode="build")
engine.ingest("v1", np.array([1.0, 2.0], dtype=np.float32))
engine.ingest("v2", np.array([3.0, 4.0], dtype=np.float32))
engine.finalize()

results = engine.search(np.array([1.0, 2.0], dtype=np.float32), k=2)
print(results)  # ['v1', 'v2']
If this runs without errors, brinicle is installed and working correctly.