Metadata-Version: 2.4
Name: hebbrix
Version: 2.5.0
Summary: Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs
Author-email: Hebbrix Team <support@hebbrix.com>
Maintainer-email: Hebbrix Team <support@hebbrix.com>
License: MIT License
        
        Copyright (c) 2025 Hebbrix
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://hebbrix.com
Project-URL: Documentation, https://docs.hebbrix.com
Project-URL: Source, https://github.com/Hebbrix/hebbrix-python
Project-URL: Issues, https://github.com/Hebbrix/hebbrix-python/issues
Project-URL: Support, https://www.hebbrix.com/contact
Project-URL: API Reference, https://api.hebbrix.com/docs
Keywords: ai,memory,agents,llm,chatbot,assistant,ml,reinforcement-learning,knowledge-graph,vector-search,rag,temporal,procedural-memory,working-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8<6.0.0,>=5.0.4; python_full_version < "3.8.1" and extra == "dev"
Requires-Dist: flake8>=6.0.0; python_full_version >= "3.8.1" and extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: cryptography>=42.0.0; extra == "dev"
Dynamic: license-file

# Hebbrix Python SDK

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

## Install

```bash
pip install hebbrix==2.5.0
```

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

```python
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:

```python
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:

```python
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`](https://api.hebbrix.com/v1/release). The public OpenAPI is
[`/openapi.json`](https://api.hebbrix.com/openapi.json).

- [Documentation](https://docs.hebbrix.com)
- [API reference](https://api.hebbrix.com/docs)
- [PyPI files](https://pypi.org/project/hebbrix/#files)
- [Support](https://www.hebbrix.com/contact)

## License

MIT. See `LICENSE` in the distribution.
