Installation

Install

The SDK is published to PyPI as brain-db-sdk. The importable module is brain_db_sdk.

pip install brain-db-sdk

If your project uses Poetry, uv, or Hatch, add the dependency through the usual channels — there is no SDK-specific build step.

poetry add brain-db-sdk
uv add brain-db-sdk

Runtime dependencies

The HTTP tier (BrainHttpClient) has zero third-party runtime dependencies — it is built on the standard library's urllib.request. The wire tier (BrainClient) depends on cbor2 for CBOR payload encoding. There is no compiled extension; the SDK is pure Python.

Import and version

import brain_db_sdk
print(brain_db_sdk.__version__)  # '0.1.0'

The public surface is exposed from the top-level package:

from brain_db_sdk import (
    BrainHttpClient,          # HTTP tier
    BrainClient, Auth, ClientConfig, Pool,   # wire tier
    EncodeBuilder, RecallBuilder, ForgetBuilder,   # request builders
    RecallAnswer, AnswerKind, WaitMode,
    RetryPolicy, with_retry,
    BrainError,               # error base
)
from brain_db_sdk.http import HttpRetryPolicy, BrainHttpError

Verify the install

The cheapest end-to-end check depends on which client you use.

from brain_db_sdk import BrainHttpClient

client = BrainHttpClient("sk-...", base_url="https://api.arc-labs.ai")
me = client.whoami()
print(me.namespace, me.agent_id)

from brain_db_sdk import BrainClient, Auth

with BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token")) as client:
    print(client.namespace)          # the tenant the server bound you to
    caps = client.capabilities()     # GET_CAPABILITIES
    print(caps)

For a CI import smoke test, a single shell line is enough:

python -c "import brain_db_sdk as b; print(b.__version__, b.BrainHttpClient, b.BrainClient)"

Troubleshooting the install

• BrainHttpError with status == 0 — a transport or timeout failure: DNS, firewall, or the wrong base_url. The default base_url is http://127.0.0.1:8080; point it at your edge for hosted deployments.
• BrainHttpError with status == 401 — the API key is rejected.
• ProtocolError / VersionMismatch on the wire client — the server is reachable but the handshake failed. Check the port (the shard's TCP port, e.g. 9090) and the token.