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, 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.

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.0

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.0
File Size Uploaded Provenance Actions
aivm_brain-0.1.0.tar.gz 15.1 kB Without provenance Details for aivm_brain-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aivm-brain 0.1.0
File Interpreter ABI Platform Actions
aivm_brain-0.1.0-py3-none-any.whl Python 3 none any Details for aivm_brain-0.1.0-py3-none-any.whl

Total release size: 28.6 kB

Release files / aivm_brain-0.1.0.tar.gz

Download URL aivm_brain-0.1.0.tar.gz
Size 15.1 kB
Tags Source
SHA-256 checksum
How to use checksums
768a06af994626dbd491156ec2c088b1e8252f564066a595e6c3e01ec3c9c58f
BLAKE2b-256 checksum
How to use checksums
3e4c1b41c5ebc92ac10c8896513a29ba039cc11c18344a6badb9770b3ba5af20
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.0-py3-none-any.whl

Download URL aivm_brain-0.1.0-py3-none-any.whl
Size 13.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c8d84d369d9e1d56a3b64d6898ec7c977d061959590a200ed54bdae5a3cba972
BLAKE2b-256 checksum
How to use checksums
935bbb77483dc440a296c42bf99c1ac159f1d954c5eebe3dd620232dea9d84a5
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.0

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.0 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