hebbrix 2.3.2__tar.gz → 2.4.1__tar.gz

{hebbrix-2.3.2 → hebbrix-2.4.1}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.4.1 — 2026-08-27
+
+- Make every async and sync readiness deadline preserve the original durable
+  receipt and raise top-level `IndexingTimeoutError`, including single writes,
+  batches, inference jobs, and direct updates.
+- Normalize memory/job/status/request/outbox/idempotency recovery metadata and
+  preserve transport-only `Location`, request, retry, event, and replay headers.
+
+## 2.4.0 — 2026-08-27
+
+- Reconcile every exported advanced method with the canonical public OpenAPI,
+  including temporal, working-memory, consolidation, memory-tool, and RL routes.
+- Add a route-manifest release gate and clean-wheel installation verification.
+- Treat durable-but-indexing batch results as `202`, poll them through the SDK,
+  and raise `IndexingTimeoutError` with the durable receipt on client deadline.
+- Preserve structured entitlement metadata in `EntitlementError`.
+- Keep advanced resources async-only and document the sync-client boundary.
+- Withdraw the experimental World Model from the public SDK until a trained,
+  versioned production model artifact and serving contract exist.
+- Publish compatibility through `GET /v1/release`; replace the broken public
+  repository link with valid artifact and support links.
+
 ## 2.3.2 — 2026-08-27
 
 - Align procedure create/list/get/update/execute/delete with the canonical

hebbrix-2.4.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: hebbrix
+Version: 2.4.1
+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-Expression: MIT
+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.4.1
+```
+
+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.

hebbrix-2.4.1/README.md

@@ -0,0 +1,127 @@
+# Hebbrix Python SDK
+
+Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
+
+## Install
+
+```bash
+pip install hebbrix==2.4.1
+```
+
+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.

hebbrix-2.4.1/hebbrix/__init__.py

@@ -0,0 +1,42 @@
+"""Typed async-first client for Hebbrix memory and outcome-learning APIs.
+
+The public surface and its plan/role restrictions are documented by the
+production OpenAPI and ``GET /v1/users/me/capabilities``. The experimental
+World Model is intentionally absent from this release.
+"""
+
+__version__ = "2.4.1"
+__author__ = "Hebbrix Team"
+__license__ = "MIT"
+
+from hebbrix.chat import MemoryChat
+from hebbrix.client import MemoryClient
+from hebbrix.exceptions import (
+    AuthenticationError,
+    EntitlementError,
+    HebbrixError,
+    IndexingTimeoutError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from hebbrix.models import EvidenceClaim, GroundingReceipt, SearchSafetyEnvelope
+from hebbrix.sync_client import SyncMemoryClient
+
+__all__ = [
+    "MemoryClient",
+    "SyncMemoryClient",
+    "MemoryChat",
+    "HebbrixError",
+    "AuthenticationError",
+    "EntitlementError",
+    "IndexingTimeoutError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "GroundingReceipt",
+    "EvidenceClaim",
+    "SearchSafetyEnvelope",
+]

{hebbrix-2.3.2 → hebbrix-2.4.1}/hebbrix/client.py

@@ -10,6 +10,7 @@ from typing import Any, Dict, List, Optional
 import httpx
 from hebbrix.exceptions import (
     AuthenticationError,
+    EntitlementError,
     HebbrixError,
     NotFoundError,
     RateLimitError,
@@ -30,7 +31,6 @@ from hebbrix.resources import (
     SearchResource,
     TemporalResource,
     WorkingMemoryResource,
-    WorldModelResource,
 )
 
 
@@ -85,13 +85,12 @@ class MemoryClient:
         self.working_memory = WorkingMemoryResource(self)
         self.consolidation = ConsolidationResource(self)
         self.memory_tools = MemoryToolsResource(self)
-        self.world_model = WorldModelResource(self)
 
     def _get_headers(self) -> Dict[str, str]:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.3.2",
+            "User-Agent": "hebbrix-python/2.4.1",
         }
 
         if self.api_key:
@@ -108,23 +107,71 @@ class MemoryClient:
 
         try:
             error_data = response.json()
-            message = error_data.get("error", {}).get("message", response.text)
         except Exception:
-            message = response.text
+            error_data = {}
+
+        envelope = error_data.get("error") or error_data.get("detail") or {}
+        if not isinstance(envelope, dict):
+            envelope = {"message": str(envelope)}
+        nested = envelope.get("message")
+        details = nested if isinstance(nested, dict) else envelope
+        message = (
+            (details.get("message") if isinstance(details, dict) else None)
+            or (nested if isinstance(nested, str) else None)
+            or response.text
+        )
+        code = str(details.get("code") or envelope.get("code") or "") or None
+        request_id = (
+            details.get("request_id")
+            or envelope.get("request_id")
+            or response.headers.get("X-Request-ID")
+        )
 
         if status_code == 401:
-            raise AuthenticationError(message)
+            raise AuthenticationError(
+                message, code=code, request_id=request_id, details=details
+            )
         elif status_code == 404:
-            raise NotFoundError(message)
+            raise NotFoundError(
+                message, code=code, request_id=request_id, details=details
+            )
         elif status_code == 422:
             errors = error_data.get("error", {}).get("details", [])
-            raise ValidationError(message, errors=errors)
+            raise ValidationError(
+                message,
+                errors=errors,
+                code=code,
+                request_id=request_id,
+                details=details,
+            )
         elif status_code == 429:
-            raise RateLimitError(message)
+            raise RateLimitError(
+                message, code=code, request_id=request_id, details=details
+            )
         elif status_code >= 500:
-            raise ServerError(message)
+            raise ServerError(
+                message, code=code, request_id=request_id, details=details
+            )
+        elif status_code in {402, 403} and (
+            "ENTITLEMENT" in str(code or "")
+            or details.get("error")
+            in {"feature_not_available", "tier_upgrade_required"}
+        ):
+            raise EntitlementError(
+                message,
+                status_code=status_code,
+                code=code,
+                request_id=request_id,
+                details=details,
+            )
         else:
-            raise HebbrixError(message, status_code=status_code)
+            raise HebbrixError(
+                message,
+                status_code=status_code,
+                code=code,
+                request_id=request_id,
+                details=details,
+            )
 
     async def request(
         self,
@@ -153,7 +200,24 @@ class MemoryClient:
         if response.status_code >= 400:
             self._handle_error(response)
 
-        return response.json() if response.text else {}
+        payload = response.json() if response.text else {}
+        if isinstance(payload, dict):
+            # Preserve transport-only recovery identifiers on durable 202
+            # receipts.  The resource layer needs these values if its local
+            # readiness deadline expires after the write has committed.
+            recovery_headers = {
+                "request_id": response.headers.get("X-Request-ID"),
+                "status_url": response.headers.get("Location"),
+                "outbox_event_id": response.headers.get("X-Hebbrix-Index-Event"),
+                "retry_after": response.headers.get("Retry-After"),
+            }
+            for key, value in recovery_headers.items():
+                if value and not payload.get(key):
+                    payload[key] = value
+            replay = response.headers.get("X-Idempotent-Replay")
+            if replay is not None and "idempotency_replay" not in payload:
+                payload["idempotency_replay"] = replay.casefold() == "true"
+        return payload
 
     async def get(self, path: str, **kwargs) -> Dict[str, Any]:
         """Make a GET request."""

hebbrix-2.4.1/hebbrix/exceptions.py

@@ -0,0 +1,135 @@
+"""
+Hebbrix SDK Exceptions
+"""
+
+
+class HebbrixError(Exception):
+    """Base exception for Hebbrix SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = None,
+        *,
+        code: str = None,
+        request_id: str = None,
+        details: dict = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class EntitlementError(HebbrixError):
+    """The authenticated account lacks the plan or role for an operation."""
+
+    def __init__(self, message: str, *, status_code: int, **kwargs):
+        super().__init__(message, status_code=status_code, **kwargs)
+
+
+class IndexingTimeoutError(TimeoutError):
+    """A durable write did not become searchable before the client deadline.
+
+    The write has already committed when this exception is raised.  Recovery
+    metadata therefore lives on the exception so callers can resume polling or
+    safely replay the *same* request with the same idempotency key instead of
+    issuing an uncorrelated duplicate write.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        receipt: dict,
+        *,
+        idempotency_key: str = None,
+    ):
+        self.receipt = dict(receipt or {})
+
+        candidates = [
+            *(self.receipt.get("memory_ids") or []),
+            self.receipt.get("memory_id"),
+            self.receipt.get("id"),
+            *(
+                item.get("memory_id") or item.get("id")
+                for item in (self.receipt.get("results") or [])
+                if isinstance(item, dict)
+            ),
+        ]
+        self.memory_ids = list(
+            dict.fromkeys(str(value) for value in candidates if value)
+        )
+        self.job_id = self.receipt.get("job_id")
+        self.status_url = self.receipt.get("status_url")
+        if not self.status_url and self.memory_ids:
+            self.status_url = f"/v1/memories/{self.memory_ids[0]}"
+        if not self.status_url and self.job_id:
+            self.status_url = f"/v1/memory-jobs/{self.job_id}"
+
+        self.request_id = self.receipt.get("request_id")
+        self.outbox_event_id = self.receipt.get("outbox_event_id")
+        self.indexing_event_id = (
+            self.receipt.get("indexing_event_id") or self.outbox_event_id
+        )
+        self.event_id = self.receipt.get("event_id") or self.indexing_event_id
+        self.idempotency_key = idempotency_key or self.receipt.get("idempotency_key")
+        self.idempotency_replay = self.receipt.get(
+            "idempotency_replay",
+            self.receipt.get("idempotency_replayed"),
+        )
+        self.retry_after = self.receipt.get("retry_after")
+        self.recovery = {
+            key: value
+            for key, value in {
+                "memory_ids": list(self.memory_ids),
+                "job_id": self.job_id,
+                "status_url": self.status_url,
+                "request_id": self.request_id,
+                "outbox_event_id": self.outbox_event_id,
+                "indexing_event_id": self.indexing_event_id,
+                "event_id": self.event_id,
+                "idempotency_key": self.idempotency_key,
+                "idempotency_replay": self.idempotency_replay,
+                "retry_after": self.retry_after,
+            }.items()
+            if value not in (None, "", [])
+        }
+        super().__init__(message)
+
+
+class AuthenticationError(HebbrixError):
+    """Raised when authentication fails."""
+
+    def __init__(self, message: str = "Authentication failed", **kwargs):
+        super().__init__(message, status_code=401, **kwargs)
+
+
+class ValidationError(HebbrixError):
+    """Raised when request validation fails."""
+
+    def __init__(self, message: str, errors: list = None, **kwargs):
+        self.errors = errors or []
+        super().__init__(message, status_code=422, **kwargs)
+
+
+class NotFoundError(HebbrixError):
+    """Raised when a resource is not found."""
+
+    def __init__(self, message: str = "Resource not found", **kwargs):
+        super().__init__(message, status_code=404, **kwargs)
+
+
+class RateLimitError(HebbrixError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", **kwargs):
+        super().__init__(message, status_code=429, **kwargs)
+
+
+class ServerError(HebbrixError):
+    """Raised when server returns 5xx error."""
+
+    def __init__(self, message: str = "Internal server error", **kwargs):
+        super().__init__(message, status_code=500, **kwargs)