Skip to main content

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)

Source distribution for aivm-brain 0.1.1
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)

Table of built distributions (wheels) for aivm-brain 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page