hebbrix 2.4.0__tar.gz → 2.4.1__tar.gz

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

@@ -1,5 +1,13 @@
 # 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,

{hebbrix-2.4.0/hebbrix.egg-info → hebbrix-2.4.1}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.4.0
+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://pypi.org/project/hebbrix/#files
+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
@@ -46,7 +47,7 @@ Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 ## Install
 
 ```bash
-pip install hebbrix==2.4.0
+pip install hebbrix==2.4.1
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -87,8 +88,37 @@ 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, durable memory IDs, and status URL. Reuse the same idempotency key with
-the same body to recover the same logical resources.
+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:
 

{hebbrix-2.4.0 → hebbrix-2.4.1}/README.md

@@ -5,7 +5,7 @@ Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 ## Install
 
 ```bash
-pip install hebbrix==2.4.0
+pip install hebbrix==2.4.1
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -46,8 +46,37 @@ 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, durable memory IDs, and status URL. Reuse the same idempotency key with
-the same body to recover the same logical resources.
+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:
 

{hebbrix-2.4.0 → hebbrix-2.4.1}/hebbrix/__init__.py

@@ -5,7 +5,7 @@ production OpenAPI and ``GET /v1/users/me/capabilities``. The experimental
 World Model is intentionally absent from this release.
 """
 
-__version__ = "2.4.0"
+__version__ = "2.4.1"
 __author__ = "Hebbrix Team"
 __license__ = "MIT"
 

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

@@ -90,7 +90,7 @@ class MemoryClient:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.4.0",
+            "User-Agent": "hebbrix-python/2.4.1",
         }
 
         if self.api_key:
@@ -200,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)

{hebbrix-2.4.0 → hebbrix-2.4.1}/hebbrix/resources.py

@@ -457,6 +457,7 @@ class MemoriesResource(BaseResource):
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -505,11 +506,15 @@ class MemoriesResource(BaseResource):
         if idempotency_key:
             kwargs["headers"] = {"Idempotency-Key": idempotency_key}
         receipt = await self.client.post("/v1/memories/batch", **kwargs)
-        if wait_for_index and not receipt.get("searchable"):
+        if wait_for_index and not (
+            receipt.get("searchable") is True
+            and str(receipt.get("processing_status") or "").casefold() == "completed"
+        ):
             receipt = await self.wait_batch_until_searchable(
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -519,6 +524,7 @@ class MemoriesResource(BaseResource):
         *,
         timeout: float = 60.0,
         poll_interval: float = 0.5,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Poll every item in an asynchronous batch receipt to one terminal state.
 
@@ -537,11 +543,20 @@ class MemoriesResource(BaseResource):
             )
             for row in rows:
                 state = str(row.get("processing_status") or "").casefold()
+                if state == "completed" and row.get("searchable") is not True:
+                    raise RuntimeError(
+                        f"memory {row.get('id')} reported completed without "
+                        "searchable=true"
+                    )
                 if state in {"failed", "cancelled", "canceled"}:
                     raise RuntimeError(
                         f"memory {row.get('id')} indexing reached terminal state {state}"
                     )
-            if all(row.get("searchable") is True for row in rows):
+            if all(
+                row.get("searchable") is True
+                and str(row.get("processing_status") or "").casefold() == "completed"
+                for row in rows
+            ):
                 return {
                     **receipt,
                     "processing_status": "completed",
@@ -556,10 +571,14 @@ class MemoriesResource(BaseResource):
                     ],
                 }
             if time.monotonic() >= deadline:
-                raise IndexingTimeoutError(
+                timeout_error = TimeoutError(
                     f"batch was not searchable within {timeout}s; the write is durable",
-                    receipt,
                 )
+                raise IndexingTimeoutError(
+                    str(timeout_error),
+                    receipt,
+                    idempotency_key=idempotency_key,
+                ) from timeout_error
             await asyncio.sleep(max(0.05, poll_interval))
 
     async def wait_until_searchable(
@@ -597,6 +616,7 @@ class MemoriesResource(BaseResource):
         *,
         timeout: float,
         poll_interval: float,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         if (
             receipt.get("searchable") is True
@@ -619,9 +639,14 @@ class MemoriesResource(BaseResource):
                         f"memory job {job_id} reached terminal state {state}"
                     )
                 if time.monotonic() >= deadline:
-                    raise TimeoutError(
+                    timeout_error = TimeoutError(
                         f"memory job {job_id} did not become searchable within {timeout}s"
                     )
+                    raise IndexingTimeoutError(
+                        f"{timeout_error}; the write is durable",
+                        receipt,
+                        idempotency_key=idempotency_key,
+                    ) from timeout_error
                 await asyncio.sleep(max(0.05, poll_interval))
 
         candidates = [
@@ -637,11 +662,19 @@ class MemoriesResource(BaseResource):
             raise RuntimeError(
                 "wait_for_index response contained neither a memory id nor a job id"
             )
-        ready = await self.wait_until_searchable(
-            memory_id,
-            timeout=timeout,
-            poll_interval=poll_interval,
-        )
+        try:
+            ready = await self.wait_until_searchable(
+                memory_id,
+                timeout=timeout,
+                poll_interval=poll_interval,
+            )
+        except TimeoutError as exc:
+            raise IndexingTimeoutError(
+                f"memory {memory_id} was not searchable within {timeout}s; "
+                "the write is durable",
+                receipt,
+                idempotency_key=idempotency_key,
+            ) from exc
         receipt["searchable"] = True
         receipt["processing_status"] = "completed"
         receipt["status_url"] = ready.get("status_url") or f"/v1/memories/{memory_id}"
@@ -793,6 +826,8 @@ class MemoriesResource(BaseResource):
         importance: Optional[float] = None,
         metadata: Optional[Dict[str, Any]] = None,
         wait_for_index: Optional[bool] = None,
+        index_timeout: float = 60.0,
+        index_poll_interval: float = 0.5,
     ) -> Dict[str, Any]:
         """
         Update a memory.
@@ -816,7 +851,15 @@ class MemoriesResource(BaseResource):
         if wait_for_index is not None:
             data["wait_for_index"] = wait_for_index
 
-        return await self.client.patch(f"/v1/memories/{memory_id}", json=data)
+        receipt = await self.client.patch(f"/v1/memories/{memory_id}", json=data)
+        if wait_for_index is True:
+            receipt = {**receipt, "id": receipt.get("id") or memory_id}
+            receipt = await self._ensure_searchable_receipt(
+                receipt,
+                timeout=index_timeout,
+                poll_interval=index_poll_interval,
+            )
+        return receipt
 
     async def delete(self, memory_id: str) -> None:
         """

{hebbrix-2.4.0 → hebbrix-2.4.1}/hebbrix/sync_client.py

@@ -100,6 +100,7 @@ class SyncMemoriesResource:
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -141,11 +142,15 @@ class SyncMemoriesResource:
         if idempotency_key:
             kwargs["headers"] = {"Idempotency-Key": idempotency_key}
         receipt = self.client.post("/v1/memories/batch", **kwargs)
-        if wait_for_index and not receipt.get("searchable"):
+        if wait_for_index and not (
+            receipt.get("searchable") is True
+            and str(receipt.get("processing_status") or "").casefold() == "completed"
+        ):
             receipt = self.wait_batch_until_searchable(
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -155,6 +160,7 @@ class SyncMemoriesResource:
         *,
         timeout: float = 60.0,
         poll_interval: float = 0.5,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Poll every item in an asynchronous batch receipt until searchable."""
 
@@ -166,11 +172,20 @@ class SyncMemoriesResource:
             rows = [self.get(memory_id) for memory_id in memory_ids]
             for row in rows:
                 state = str(row.get("processing_status") or "").casefold()
+                if state == "completed" and row.get("searchable") is not True:
+                    raise RuntimeError(
+                        f"memory {row.get('id')} reported completed without "
+                        "searchable=true"
+                    )
                 if state in {"failed", "cancelled", "canceled"}:
                     raise RuntimeError(
                         f"memory {row.get('id')} indexing reached terminal state {state}"
                     )
-            if all(row.get("searchable") is True for row in rows):
+            if all(
+                row.get("searchable") is True
+                and str(row.get("processing_status") or "").casefold() == "completed"
+                for row in rows
+            ):
                 return {
                     **receipt,
                     "processing_status": "completed",
@@ -185,10 +200,14 @@ class SyncMemoriesResource:
                     ],
                 }
             if time.monotonic() >= deadline:
-                raise IndexingTimeoutError(
+                timeout_error = TimeoutError(
                     f"batch was not searchable within {timeout}s; the write is durable",
-                    receipt,
                 )
+                raise IndexingTimeoutError(
+                    str(timeout_error),
+                    receipt,
+                    idempotency_key=idempotency_key,
+                ) from timeout_error
             time.sleep(max(0.05, poll_interval))
 
     def wait_until_searchable(
@@ -224,6 +243,7 @@ class SyncMemoriesResource:
         *,
         timeout: float,
         poll_interval: float,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         if (
             receipt.get("searchable") is True
@@ -232,11 +252,19 @@ class SyncMemoriesResource:
             return receipt
         job_id = str(receipt.get("job_id") or "")
         if job_id:
-            job = SyncMemoryJobsResource(self.client).wait(
-                job_id,
-                timeout=timeout,
-                poll_interval=poll_interval,
-            )
+            try:
+                job = SyncMemoryJobsResource(self.client).wait(
+                    job_id,
+                    timeout=timeout,
+                    poll_interval=poll_interval,
+                )
+            except TimeoutError as exc:
+                raise IndexingTimeoutError(
+                    f"memory job {job_id} did not become searchable within {timeout}s; "
+                    "the write is durable",
+                    receipt,
+                    idempotency_key=idempotency_key,
+                ) from exc
             if str(job.get("status") or "").casefold() != "completed":
                 raise RuntimeError(f"memory job {job_id} did not complete")
             receipt.update(job)
@@ -256,11 +284,19 @@ class SyncMemoriesResource:
             raise RuntimeError(
                 "wait_for_index response contained neither a memory id nor a job id"
             )
-        ready = self.wait_until_searchable(
-            memory_id,
-            timeout=timeout,
-            poll_interval=poll_interval,
-        )
+        try:
+            ready = self.wait_until_searchable(
+                memory_id,
+                timeout=timeout,
+                poll_interval=poll_interval,
+            )
+        except TimeoutError as exc:
+            raise IndexingTimeoutError(
+                f"memory {memory_id} was not searchable within {timeout}s; "
+                "the write is durable",
+                receipt,
+                idempotency_key=idempotency_key,
+            ) from exc
         receipt["searchable"] = True
         receipt["processing_status"] = "completed"
         receipt["status_url"] = ready.get("status_url") or f"/v1/memories/{memory_id}"
@@ -307,6 +343,8 @@ class SyncMemoriesResource:
         importance: Optional[float] = None,
         metadata: Optional[Dict[str, Any]] = None,
         wait_for_index: Optional[bool] = None,
+        index_timeout: float = 60.0,
+        index_poll_interval: float = 0.5,
     ) -> Dict[str, Any]:
         payload = {
             "content": content,
@@ -314,10 +352,18 @@ class SyncMemoriesResource:
             "metadata": metadata,
             "wait_for_index": wait_for_index,
         }
-        return self.client.patch(
+        receipt = self.client.patch(
             f"/v1/memories/{memory_id}",
             json={key: value for key, value in payload.items() if value is not None},
         )
+        if wait_for_index is True:
+            receipt = {**receipt, "id": receipt.get("id") or memory_id}
+            receipt = self._ensure_searchable_receipt(
+                receipt,
+                timeout=index_timeout,
+                poll_interval=index_poll_interval,
+            )
+        return receipt
 
     def delete(self, memory_id: str) -> Dict[str, Any]:
         return self.client.delete(f"/v1/memories/{memory_id}")
@@ -743,7 +789,7 @@ class SyncMemoryClient:
         self.source = source or os.getenv("HEBBRIX_SOURCE")
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.4.0",
+            "User-Agent": "hebbrix-python/2.4.1",
         }
         if api_key:
             headers["Authorization"] = f"Bearer {api_key}"
@@ -833,7 +879,21 @@ class SyncMemoryClient:
         response = self._client.request(method, path, **kwargs)
         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):
+            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
 
     def get(self, path: str, **kwargs) -> Dict[str, Any]:
         return self.request("GET", path, **kwargs)