Hebbrix Python SDK

Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.

This branch is the 2.6.0rc1 prerelease. Native experience operations require the matching backend schema b5c6d7e8f959; they are not yet enabled on the public production API. Keep 2.5.0 for the current stable deployment. A prerelease SDK does not enable autonomous execution or demonstrate a learning advantage.

Install

pip install hebbrix==2.6.0rc1

Python 3.8+ is supported. MemoryClient is asynchronous. SyncMemoryClient supports the core collection, memory, search, correction, procedure, and ProofLoop workflows; advanced temporal, working-memory, consolidation, memory-tool, and RL resources are currently async-only.

Quick start

import asyncio
from hebbrix import MemoryClient

async def main():
    async with MemoryClient(api_key="hbx_your_api_key") as client:
        collection = await client.collections.create(name="Support memory")
        memory = await client.memories.create(
            collection_id=collection["id"],
            content="Customer prefers concise replies",
            wait_for_index=True,
            idempotency_key="customer-42-preference-v1",
        )
        results = await client.search(
            "How should replies be formatted?",
            collection_id=collection["id"],
        )
        print(memory, results)

asyncio.run(main())

Durable readiness

Memory writes return either a searchable completion or a durable 202 receipt. A durable receipt means the database commit succeeded while indexing is still converging; it is not a failure and does not justify a duplicate write.

When wait_for_index=True, the SDK accepts that receipt and polls the documented status URL. It returns only after searchable=true. If the caller's deadline expires, it raises IndexingTimeoutError; the exception retains the original receipt plus normalized memory_ids, job_id, status_url, request_id, outbox_event_id, retry timing, and idempotency replay metadata when available. The synchronous and asynchronous single, batch, inference-job, and update readiness paths share this behavior. The SDK never repeats the write while it polls.

Catch the typed deadline without discarding the durable acceptance:

from hebbrix import IndexingTimeoutError

try:
    created = await client.memories.create(
        content="Customer prefers concise replies",
        wait_for_index=True,
        idempotency_key="customer-42-preference-v1",
        index_timeout=5,
    )
except IndexingTimeoutError as exc:
    # Resume observation; do not submit an unrelated second write.
    if exc.memory_ids:
        created = await client.memories.wait_until_searchable(exc.memory_ids[0])
    elif exc.job_id:
        created = await client.memory_jobs.wait(exc.job_id)

For a timed-out batch, pass exc.receipt to memories.wait_batch_until_searchable(...). Alternatively, replay the exact same body with exc.idempotency_key; a changed body with the same key is rejected by the API rather than creating a second logical write. For an update, resume polling exc.memory_ids[0] because the relational edit already committed.

For an asynchronous batch receipt:

receipt = await client.memories.create_batch(
    [{"content": "First fact"}, {"content": "Second fact"}],
    collection_id="collection-42",
    wait_for_index=False,
    idempotency_key="import-42",
)
completed = await client.memories.wait_batch_until_searchable(receipt)

Pagination

collections.list() returns the current page's collection items for backward compatibility. Use collections.list_page() when cursor metadata is required. Memory resources provide the same list()/list_page() distinction.

Advanced capabilities and entitlements

The async client exposes the canonical /v1 temporal, working-memory, consolidation, memory-tool, and RL contracts. RL metrics and evaluation require the Pro plan. Process-wide RL training and checkpoint mutation require an admin role. Entitlement failures raise EntitlementError and preserve the stable error code, current/required plan, request ID, and support action.

The experimental World Model is intentionally not exported by this public SDK. It remains withdrawn until a trained, versioned production model artifact and an end-to-end public serving contract are available.

The authoritative account capability matrix is available from GET /v1/users/me/capabilities.

Release compatibility

The production API publishes exact build and artifact compatibility at GET /v1/release. The public OpenAPI is /openapi.json.

• Documentation
• API reference
• PyPI files
• Support

License

MIT. See LICENSE in the distribution.

Native experience workflow (prerelease)

The current source includes client.experiences, bounded reflection workers, separate lesson review/revision and explicit one-use execution admission. These methods require the matching new backend; the published 2.5.0 release does not include this extension. The candidate package supplies hebbrix-reflect --help. Importing it does not call a model, approve a lesson or execute a tool.

See docs/native-experience-operations.md for role scopes, uncertain-call recovery, exact-request binding and policy rollback. Do not treat a lesson, score, review or issued permit as execution permission.