Wire client

Connecting

The client opens a TCP connection, runs the handshake (HELLO → WELCOME → AUTH → AUTH_OK), and returns a client bound to the session the server granted.

BrainClient.connect(host: str, port: int, auth: Auth) -> BrainClient
BrainClient.connect_with(host: str, port: int, config: ClientConfig) -> BrainClient

from brain_db_sdk import BrainClient, Auth

# Simple path — default transport settings.
client = BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token"))

# Or use it as a context manager; __exit__ sends BYE and closes the socket.
with BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token")) as client:
    ...

connect is the shorthand; connect_with takes an explicit ClientConfig for full control.

Auth

Auth is mandatory — the credential is the connection's whole identity, and the server resolves (namespace, agent, permissions) from it. There is no anonymous mode.

from brain_db_sdk import Auth

auth = Auth.token(b"my-token")

ClientConfig

connect_with takes a ClientConfig. auth is the only required field; the rest default to a local/dev server (wire version 1, streaming advertised).

from brain_db_sdk import BrainClient, Auth, ClientConfig

config = ClientConfig(
    auth=Auth.token(b"my-token"),
    client_id="my-service",
    request_timeout=60.0,
)
client = BrainClient.connect_with("127.0.0.1", 9090, config)

The session

After the handshake the client exposes the session the server granted:

print(client.namespace)
print(client.session.chosen_version, client.session.bound_shard_id)
print(client.session.permissions)

Multiplexing and pooling

A single BrainClient multiplexes many concurrent requests over one socket — a background reader thread demultiplexes responses by stream_id, so the verbs are thread-safe and many requests can be in flight at once from multiple threads. You do not need a pool for concurrency.

A Pool buys socket-level parallelism — spreading load across N independent TCP connections (and N server-side connection slots), and isolating a slow socket from the rest:

from brain_db_sdk import Pool, Auth

with Pool.connect("127.0.0.1", 9090, size=4, auth=Auth.token(b"my-token")) as pool:
    client = pool.get()          # round-robin borrow
    client.recall(...)

The verb surface

BrainClient serves the full v1 surface. Every verb takes a wire request dataclass and returns a typed response:

• Core memory — encode, recall (recall_frames), forget, memory_list (memory_list_frames), memory_inspect.
• Edges — link, unlink.
• Typed graph — create_entity, get_entity, resolve_entity, update_entity, rename_entity, merge_entities, unmerge_entity, tombstone_entity, list_entities; create_statement, get_statement, supersede_statement, tombstone_statement, retract_statement, statement_history, list_statements; create_relation, get_relation, supersede_relation, tombstone_relation, traverse_relations, list_relations_from, list_relations_to; upload_schema, get_schema, validate_schema, list_schemas; graph_fetch.
• Transactions — txn_begin, txn_commit, txn_abort.
• Subscriptions — subscribe.
• Reasoning — plan, reason, materialize_procedural.
• Introspection — capabilities, extractor_list, query_explain, query_trace.

The core verbs are covered in Encode, Recall, and Forget; the graph, transaction, and subscription verbs in Typed graph.

Closing

client.close()   # sends BYE, then closes the socket

Or use the context-manager form (with BrainClient.connect(...) as client:), which closes on exit.