Brain Python SDK

Install from the checkout#

From brain-platform/, with Python 3.12 or newer:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[api]'

This installs the brain package and its API dependencies from the checkout.

Configure a server-side client#

import os
from uuid import UUID
import httpx
from brain.client.application_conversations import ApplicationConversations

with httpx.Client(base_url=os.environ["BRAIN_API_BASE_URL"], timeout=10) as transport:
    conversations = ApplicationConversations(
        transport,
        brain_id=os.environ["BRAIN_ID"],
        connection_id=UUID(os.environ["BRAIN_APPLICATION_CONNECTION_ID"]),
        credential=os.environ["BRAIN_APPLICATION_CREDENTIAL"],
    )
    context = conversations.recall("customer-17", limit=20, max_context_bytes=24000)
    if context["context_status"] == "prepared":
        prepared = context["prepared"]
        context_text = prepared["unit"]["deterministic_text"]
        citations = prepared["spans"]

Keep the credential on your server and authorize each user’s thread before calling recall. Run the quickstart with a test connection.

Handle the result#

prepared means context is available. Use its rendered text in your application and keep the citations beside it. Check has_more before assuming you have all eligible messages.

empty means there is no current context for this thread. budget_limited means messages exist but none fits the requested byte budget; increase it within the API limits. These are normal response states, separate from HTTP errors.

A response excerpt for one selected message:

{
  "context_status": "prepared",
  "selected_count": 1,
  "has_more": false,
  "omission_reasons": []
}

Methods#

Method	Behavior
`ingest(export_bytes)`	Validate and save a supported message export; return a per-entry manifest. Check every outcome before the next step.
`recall(thread_id, limit=20, max_context_bytes=24000)`	Read current bounded source context for an exact thread. Validates request bounds locally; propagates HTTP and transport failures.
`receipt(receipt_id)`	Read a saved receipt by UUID.
`original(version_id)`	Read a current retained original by UUID; stale evidence is refused.
`context(version_ids)`	Prepare an explicit ordered current selection from one thread.
`ingest_context(export_bytes)`	Import, then prepare context for each thread after the complete import succeeds.
`catalog()`, `query(version_ids, plan)`	Inspect and query bounded literal metadata over current selected versions.

Withdrawal uses the existing authenticated HTTP route; the client has no withdrawal convenience method. The complete quickstart demonstrates it.

Export and replay#

{
  "format": "brain-application-conversation-export-v1",
  "export_id": "stable-import-01",
  "messages": [{
    "external_id": "message-1", "thread_id": "customer-17",
    "author_id": null, "role": "human", "occurred_at": null,
    "text": "Please call after 6 pm.", "expected_version_id": null
  }]
}

An export contains 1–60 messages and is bounded to 1 MiB. Its ID uses 1–64 ASCII letters, digits or ._:-. Duplicate message identities and malformed envelopes are refused; individual message validation failures appear in the manifest.

The manifest separates saved, rejected, unknown and not_attempted. An uncertain write stops later writes. The client sends no automatic retry, and a saved manifest is not permission to skip entries. Explicitly replay the identical whole export with the same ID, order and contents; the server owns idempotency. Changing the order changes entry keys and can conflict.

For a correction, create a new stable export ID and include the current expected_version_id. Preserve the old source receipt for lineage. Request and evidence reference.

Brain for Python.

Install from the checkout#

Configure a server-side client#

Handle the result#

Methods#

Export and replay#