aivm-brain (Python SDK)
Official Python client for the AIVM Brain memory API — add,
search, get, list, update, delete memories plus ask, with typed methods
and models instead of hand-written HTTP. Ships sync (AivmBrain) and async
(AsyncAivmBrain) clients sharing one transport/error/serialization core.
Install
pip install aivm-brain
Requires Python ≥ 3.9. Runtime deps: httpx, pydantic v2.
Authentication
Use an AIVM agent key (ak_live_…). Provide it explicitly or via the
AIVM_API_KEY environment variable; if neither is set, constructing the client
raises ConfigurationError. The key is sent as Authorization: Bearer <key> and
is never logged. Server-side use only — do not embed a key in a browser or
mobile app.
from aivm_brain import AivmBrain
brain = AivmBrain(api_key="ak_live_...") # explicit
brain = AivmBrain() # or read AIVM_API_KEY from the env
Options: AivmBrain(api_key=None, tenant_id=None, base_url=None, timeout=30.0, retrieval_timeout=120.0, max_retries=2).
base_url defaults to AIVM_BASE_URL then https://brain-be.dev.aivm.io (override it to
point at a self-hosted brain). Pass
tenant_id for a tenant-scoped key (sent as x-tenant-id); omit for personal keys.
Why search and ask get their own timeout
They are not lookups. Both run retrieval plus answer synthesis server-side — the brain embeds
your question, retrieves, and has a model write the answer — and the backend allows itself ~120s to
do it. Putting them on the 30s CRUD timeout made the SDK hang up on requests the server was still
working on, raising APITimeoutError on a perfectly healthy call. retrieval_timeout covers those
two methods; timeout still keeps CRUD fast.
Quickstart (sync)
from aivm_brain import AivmBrain
with AivmBrain(api_key="ak_live_...") as brain:
memory = brain.memories.add(title="Q3 budget", body="…", domain="finance")
hits = brain.memories.search(query="budget", top_k=5)
print(hits.answer, [h.id for h in hits.items])
fetched = brain.memories.get(memory.id)
updated = brain.memories.update(memory.id, body="…revised…")
brain.memories.delete(memory.id)
reply = brain.ask(question="What is the engineering budget?")
print(reply.answer, reply.citations)
Quickstart (async)
import asyncio
from aivm_brain import AsyncAivmBrain
async def main():
async with AsyncAivmBrain(api_key="ak_live_...") as brain:
memory = await brain.memories.add(title="Q3 budget", body="…")
hits = await brain.memories.search(query="budget")
print(hits.answer)
asyncio.run(main())
Pagination
memories.list(...) returns a Page with .items and .next_cursor (an opaque
string, or None on the last page). memories.list_all(...) transparently follows
the cursor and yields every memory:
for memory in brain.memories.list_all(domain="finance"):
print(memory.id, memory.title)
# async
async for memory in brain.memories.list_all():
print(memory.id)
Errors
Every non-2xx response raises a typed subclass of AivmError, each carrying
.status (int or None), .code, .request_id, and .message (array messages
are joined with "; ").
| status | code | class |
|---|---|---|
| 400, 422 | invalid_request |
ValidationError |
| 401 | unauthorized |
AuthenticationError |
| 402 | payment_required |
PaymentRequiredError |
| 403 | forbidden |
PermissionError |
| 404 | not_found |
NotFoundError |
| 409 | conflict |
ConflictError |
| 413 | payload_too_large |
PayloadTooLargeError |
| 429 | rate_limited |
RateLimitError |
| 5xx | server_error |
ServerError |
| — (network) | unreachable |
APIConnectionError |
| — (timeout) | timeout |
APITimeoutError |
from aivm_brain import AivmError, NotFoundError
try:
brain.memories.get("does-not-exist")
except NotFoundError as exc:
print(exc.status, exc.code, exc.request_id)
except AivmError as exc: # catch-all base
print(exc.message)
Retries & timeout
Requests time out after timeout seconds (default 30). Only idempotent reads
(memories.get, memories.list, and the pages behind list_all) are retried, on
429 / 5xx / network / timeout, with jittered exponential backoff (base ~0.5s,
default max_retries=2); a Retry-After header on a 429 is honored. Writes
(add / update / delete / search / ask) are never auto-retried, so a
network blip can't double-write.
Development
python -m venv .venv
# this box has no ensurepip; bootstrap pip:
curl -sSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py && ./.venv/bin/python /tmp/get-pip.py
./.venv/bin/python -m pip install -e '.[dev]'
./.venv/bin/python -m pytest -q
The test suite replays the golden fixtures in ../shared/fixtures/ (via respx)
so this SDK and the TypeScript SDK behave identically. Tests never hit the network.
Metadata
Release files for aivm-brain 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aivm_brain-0.1.1.tar.gz | 17.0 kB | Without provenance | Details for aivm_brain-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aivm_brain-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for aivm_brain-0.1.1-py3-none-any.whl |
Total release size: 31.3 kB
Release files / aivm_brain-0.1.1.tar.gz
| Download URL | aivm_brain-0.1.1.tar.gz |
|---|---|
| Size | 17.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5c2295e53073706a634cf8edf61c274f8cd36e4860dac90de3437ccddd104eb
|
|
BLAKE2b-256 checksum How to use checksums |
8f67f529b60415c1846d83ddded2740e7ad0374d68f6711258f80c3a4e27544a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aivm_brain-0.1.1-py3-none-any.whl
| Download URL | aivm_brain-0.1.1-py3-none-any.whl |
|---|---|
| Size | 14.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29b3b6ba9f238cfb8f8451e992db1d977c1a22754998530ee20efcca78530b18
|
|
BLAKE2b-256 checksum How to use checksums |
2e22cfdbae34182e2a498ef4de153c15a59a582737f6c0f6ab60d9ce2660c584
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for aivm-brain 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.