Installation

Install

npm install @brain-db/sdk

The package is published to npm as @brain-db/sdk. It has no runtime dependencies.

Import

Both clients are named exports from the package root:

import { BrainHttpClient, BrainClient } from "@brain-db/sdk";

The package also exports the retry helpers, the error classes, the request builders, and the wire-layer types:

import {
  BrainHttpClient,
  BrainClient,
  // request builders for the wire client
  EncodeBuilder,
  RecallBuilder,
  ForgetBuilder,
  // retry
  withRetry,
  DEFAULT_RETRY_POLICY,
  NO_RETRY,
  // errors
  BrainError,
  ServerError,
  BrainTimeout,
  ConnectionClosed,
  isRetryable,
  BrainHttpError,
  SDK_VERSION,
} from "@brain-db/sdk";

The HTTP contract types are namespaced under http to avoid colliding with the wire types (both define a Capabilities, a PlanStep, and so on):

import { http } from "@brain-db/sdk";

const input: http.EncodeInput = { text: "…" };

Versioning

The current release is 0.1.0. The value is exported at runtime:

import { SDK_VERSION } from "@brain-db/sdk";
console.log(SDK_VERSION); // "0.1.0"

Brain is pre-release (v0.1.0). Until v1.0, the wire protocol and HTTP contract can change in place; pin an exact version in production.

BrainHttpClient needs a fetch. By default it uses the global fetch, available on Node 18+, modern browsers, and edge runtimes. On a runtime without a global fetch — or when you want to inject an instrumented one — pass your own:

import { BrainHttpClient } from "@brain-db/sdk";

const brain = new BrainHttpClient({
  apiKey: process.env.BRAIN_API_KEY!,
  fetch: myInstrumentedFetch,
});

If no fetch is available and none is passed, the constructor throws a BrainHttpError with code "config".

BrainClient needs Node TCP + crypto. The wire client opens a raw TCP socket (node:net) and mints 16-byte request ids with node:crypto, so it runs on Node (and Node-compatible runtimes), not in the browser. Use BrainHttpClient from browser and edge code.

Install

Import

Versioning

Runtime notes

On this page