hebbrix 2.3.0__tar.gz → 2.3.2__tar.gz

hebbrix-2.3.2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 2.3.2 — 2026-08-27
+
+- Align procedure create/list/get/update/execute/delete with the canonical
+  `/v1/procedures` REST and OpenAPI contract, including idempotent `204`
+  deletion.
+- Add explicit synchronous/asynchronous batch readiness receipts to the async
+  and synchronous clients.
+- Add batch wait helpers that poll every accepted memory, propagate terminal
+  failures, respect deadlines, and support asynchronous cancellation.
+
+## 2.3.1 — 2026-08-26
+
+- Make `wait_for_index=True` poll the authoritative memory or job readiness
+  endpoint instead of returning a non-searchable receipt.
+- Add `memories.wait_until_searchable(...)` to the async and synchronous
+  clients, with explicit timeout and terminal-failure handling.
+- Preserve valid evidence-bound search rows during a degraded or abstaining
+  server response while retaining the safety metadata; malformed and explicit
+  no-match envelopes still fail closed.
+- Keep the synchronous and asynchronous memory create, scope, idempotency, and
+  search-safety behavior aligned.
+- Add `temporal.delete_fact(fact_id)` for tenant-scoped, idempotent cleanup of
+  facts created through the temporal API.
+
+The supported server/SDK release pair is published by the server OpenAPI
+document in `info.x-hebbrix-sdk-compatibility`. Patch releases preserve the
+public API within the same major version.
+
+## 2.3.0
+
+- Added the GA scoped memory, corrections, search proof, and ProofLoop surface.

{hebbrix-2.3.0 → hebbrix-2.3.2}/MANIFEST.in

@@ -1,4 +1,5 @@
 include README.md
+include CHANGELOG.md
 include LICENSE
 include pyproject.toml
 recursive-include hebbrix *.py

{hebbrix-2.3.0/hebbrix.egg-info → hebbrix-2.3.2}/PKG-INFO

@@ -1,10 +1,31 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.3.0
+Version: 2.3.2
 Summary: Advanced Memory API for AI Agents with Reinforcement Learning - 3-line integration
 Author-email: Hebbrix Team <support@hebbrix.com>
 Maintainer-email: Hebbrix Team <support@hebbrix.com>
-License-Expression: MIT
+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: Repository, https://github.com/hebbrix/hebbrix-python
@@ -92,6 +113,22 @@ async def main():
         wait_for_index=True,
     )
 
+    # wait_for_index=True polls the returned memory status through the SDK.
+    # It returns only when searchable=true, raises on terminal failure, and
+    # raises TimeoutError if the caller's readiness deadline expires.
+
+    # Batch contract: a successful synchronous return means every accepted item
+    # is searchable. A bounded server timeout raises explicitly and is safe to
+    # retry with the same idempotency key; it is never a successful 202.
+    batch = await client.memories.create_batch(
+        [{"content": "First fact"}, {"content": "Second fact"}],
+        collection_id=collection["id"],
+        wait_for_index=True,
+        idempotency_key="import-42",
+    )
+    # For wait_for_index=False receipts:
+    # batch = await client.memories.wait_batch_until_searchable(batch)
+
     # Search memories
     results = await client.search(
         query="What programming language does user like?",

{hebbrix-2.3.0 → hebbrix-2.3.2}/README.md

@@ -51,6 +51,22 @@ async def main():
         wait_for_index=True,
     )
 
+    # wait_for_index=True polls the returned memory status through the SDK.
+    # It returns only when searchable=true, raises on terminal failure, and
+    # raises TimeoutError if the caller's readiness deadline expires.
+
+    # Batch contract: a successful synchronous return means every accepted item
+    # is searchable. A bounded server timeout raises explicitly and is safe to
+    # retry with the same idempotency key; it is never a successful 202.
+    batch = await client.memories.create_batch(
+        [{"content": "First fact"}, {"content": "Second fact"}],
+        collection_id=collection["id"],
+        wait_for_index=True,
+        idempotency_key="import-42",
+    )
+    # For wait_for_index=False receipts:
+    # batch = await client.memories.wait_batch_until_searchable(batch)
+
     # Search memories
     results = await client.search(
         query="What programming language does user like?",

{hebbrix-2.3.0 → hebbrix-2.3.2}/hebbrix/__init__.py

@@ -41,7 +41,7 @@ Features:
 - ✅ Type hints throughout
 """
 
-__version__ = "2.3.0"
+__version__ = "2.3.2"
 __author__ = "Hebbrix Team"
 __license__ = "MIT"
 

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

@@ -91,7 +91,7 @@ class MemoryClient:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.3.0",
+            "User-Agent": "hebbrix-python/2.3.2",
         }
 
         if self.api_key:

{hebbrix-2.3.0 → hebbrix-2.3.2}/hebbrix/resources.py

@@ -127,12 +127,12 @@ def _canonical_search_envelope(
         elif data.get("no_match") and (row_ids or evidence_ids):
             reason = "no_match_contains_evidence"
 
-    if (
-        reason
-        or data.get("degraded") is True
-        or data.get("no_match") is True
-        or data.get("abstain_recommended") is True
-    ):
+    # Degradation and abstention are confidence signals, not proof that the
+    # API returned no evidence.  Erasing valid, evidence-bound rows here made
+    # the SDK disagree with the REST response and converted a safe fallback
+    # into a false negative.  Fail closed only when the envelope is malformed
+    # or the server explicitly reports no match.
+    if reason or data.get("no_match") is True:
         data[rows_key] = []
         if rows_key == "results":
             data["total"] = 0
@@ -147,6 +147,8 @@ def _canonical_search_envelope(
                 "status": "no_grounded_match",
                 "reason": reason,
             }
+    elif data.get("degraded") is True or data.get("abstain_recommended") is True:
+        data["sdk_safety_reason"] = "degraded_evidence_preserved"
     return data
 
 
@@ -347,6 +349,8 @@ class MemoriesResource(BaseResource):
         tags: Optional[List[str]] = None,
         source: Optional[str] = None,
         idempotency_key: Optional[str] = None,
+        index_timeout: float = 60.0,
+        index_poll_interval: float = 0.5,
     ) -> Dict[str, Any]:
         """
         Create a memory.
@@ -422,7 +426,199 @@ class MemoriesResource(BaseResource):
         request_kwargs: Dict[str, Any] = {"json": payload}
         if idempotency_key:
             request_kwargs["headers"] = {"Idempotency-Key": idempotency_key}
-        return await self.client.post("/v1/memories", **request_kwargs)
+        receipt = await self.client.post("/v1/memories", **request_kwargs)
+        if wait_for_index:
+            receipt = await self._ensure_searchable_receipt(
+                receipt,
+                timeout=index_timeout,
+                poll_interval=index_poll_interval,
+            )
+        return receipt
+
+    async def create_batch(
+        self,
+        memories: List[Dict[str, Any]],
+        *,
+        collection_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        app_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        wait_for_index: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a durable batch with explicit synchronous/async readiness.
+
+        When ``wait_for_index`` is true, a successful return is guaranteed to
+        have ``processing_status=completed`` and ``searchable=true``. A bounded
+        server timeout raises an HTTP error and may be retried with the same
+        idempotency key; it is never returned as a successful processing state.
+        """
+
+        if not 1 <= len(memories) <= 100:
+            raise ValueError("memories must contain between 1 and 100 items")
+        if any(not str(item.get("content") or "").strip() for item in memories):
+            raise ValueError("every batch memory must contain non-empty content")
+        payload = {
+            "memories": memories,
+            "wait_for_index": wait_for_index,
+        }
+        optional = {
+            "collection_id": collection_id,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "run_id": run_id,
+            "app_id": app_id,
+            "namespace": namespace,
+        }
+        payload.update(
+            {key: value for key, value in optional.items() if value is not None}
+        )
+        kwargs: Dict[str, Any] = {"json": payload}
+        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") is True
+            and str(receipt.get("processing_status") or "").casefold() == "completed"
+        ):
+            raise RuntimeError(
+                "wait_for_index batch response was not fully searchable; retry "
+                "with the same Idempotency-Key"
+            )
+        return receipt
+
+    async def wait_batch_until_searchable(
+        self,
+        receipt: Dict[str, Any],
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> Dict[str, Any]:
+        """Poll every item in an asynchronous batch receipt to one terminal state.
+
+        Cancellation uses normal asyncio task cancellation. A failed/cancelled
+        item or a local deadline raises explicitly; a successful return means
+        every batch item reported ``searchable=true``.
+        """
+
+        memory_ids = list(dict.fromkeys(map(str, receipt.get("memory_ids") or [])))
+        if not memory_ids:
+            raise ValueError("batch receipt does not contain memory_ids")
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            rows = await asyncio.gather(
+                *(self.get(memory_id) for memory_id in memory_ids)
+            )
+            for row in rows:
+                state = str(row.get("processing_status") or "").casefold()
+                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):
+                return {
+                    **receipt,
+                    "processing_status": "completed",
+                    "searchable": True,
+                    "results": [
+                        {
+                            "id": memory_id,
+                            "memory_id": memory_id,
+                            "processing_status": "completed",
+                        }
+                        for memory_id in memory_ids
+                    ],
+                }
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"batch was not searchable within {timeout}s")
+            await asyncio.sleep(max(0.05, poll_interval))
+
+    async def wait_until_searchable(
+        self,
+        memory_id: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> Dict[str, Any]:
+        """Poll the authoritative memory status until indexing is terminal."""
+
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            memory = await self.get(memory_id)
+            state = str(memory.get("processing_status") or "").casefold()
+            if memory.get("searchable") is True:
+                return memory
+            if state == "completed":
+                raise RuntimeError(
+                    f"memory {memory_id} reported completed without searchable=true"
+                )
+            if state in {"failed", "cancelled", "canceled"}:
+                raise RuntimeError(
+                    f"memory {memory_id} indexing reached terminal state {state}"
+                )
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"memory {memory_id} was not searchable within {timeout}s"
+                )
+            await asyncio.sleep(max(0.05, poll_interval))
+
+    async def _ensure_searchable_receipt(
+        self,
+        receipt: Dict[str, Any],
+        *,
+        timeout: float,
+        poll_interval: float,
+    ) -> Dict[str, Any]:
+        if (
+            receipt.get("searchable") is True
+            and str(receipt.get("processing_status") or "").casefold() == "completed"
+        ):
+            return receipt
+        job_id = str(receipt.get("job_id") or "")
+        if job_id:
+            deadline = time.monotonic() + max(0.0, timeout)
+            while True:
+                job = await self.client.get(f"/v1/memory-jobs/{job_id}")
+                state = str(job.get("status") or "").casefold()
+                if state == "completed":
+                    receipt.update(job)
+                    receipt["searchable"] = True
+                    receipt["processing_status"] = "completed"
+                    return receipt
+                if state in {"failed", "cancelled", "canceled"}:
+                    raise RuntimeError(
+                        f"memory job {job_id} reached terminal state {state}"
+                    )
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(
+                        f"memory job {job_id} did not become searchable within {timeout}s"
+                    )
+                await asyncio.sleep(max(0.05, poll_interval))
+
+        candidates = [
+            receipt.get("id"),
+            *(
+                item.get("id") or item.get("memory_id")
+                for item in (receipt.get("results") or [])
+                if isinstance(item, dict)
+            ),
+        ]
+        memory_id = next((str(value) for value in candidates if value), "")
+        if not memory_id:
+            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,
+        )
+        receipt["searchable"] = True
+        receipt["processing_status"] = "completed"
+        receipt["status_url"] = ready.get("status_url") or f"/v1/memories/{memory_id}"
+        return receipt
 
     async def list_page(
         self,
@@ -1091,6 +1287,15 @@ class RLResource(BaseResource):
 class ProceduralResource(BaseResource):
     """Procedural memory endpoints."""
 
+    @staticmethod
+    def _unwrap_procedure(response: Dict[str, Any]) -> Dict[str, Any]:
+        procedure = response.get("procedure")
+        if isinstance(procedure, dict):
+            return procedure
+        if response.get("procedure_id") and not response.get("id"):
+            return {**response, "id": response["procedure_id"]}
+        return response
+
     async def create(
         self,
         name: str,
@@ -1116,18 +1321,19 @@ class ProceduralResource(BaseResource):
         Returns:
             Created procedure
         """
-        return await self.client.post(
-            "/procedural",
+        response = await self.client.post(
+            "/v1/procedures",
             json={
                 "name": name,
                 "description": description,
-                "trigger_condition": trigger_condition,
-                "action_sequence": action_sequence,
+                "condition": {"expression": trigger_condition},
+                "action": {"steps": action_sequence},
                 "collection_id": collection_id,
                 "category": category,
-                "metadata": metadata or {},
+                "parameters": metadata or {},
             },
         )
+        return self._unwrap_procedure(response)
 
     async def list(
         self,
@@ -1154,7 +1360,10 @@ class ProceduralResource(BaseResource):
         if category:
             params["category"] = category
 
-        return await self.client.get("/procedural", params=params)
+        response = await self.client.get("/v1/procedures", params=params)
+        return (
+            response if isinstance(response, list) else response.get("procedures", [])
+        )
 
     async def get(self, procedure_id: str) -> Dict[str, Any]:
         """
@@ -1166,7 +1375,8 @@ class ProceduralResource(BaseResource):
         Returns:
             Procedure data
         """
-        return await self.client.get(f"/procedural/{procedure_id}")
+        response = await self.client.get(f"/v1/procedures/{procedure_id}")
+        return self._unwrap_procedure(response)
 
     async def execute(
         self,
@@ -1183,10 +1393,12 @@ class ProceduralResource(BaseResource):
         Returns:
             Execution result
         """
-        return await self.client.post(
-            f"/procedural/{procedure_id}/execute",
-            json={"context": context or {}},
+        response = await self.client.post(
+            f"/v1/procedures/{procedure_id}/execute",
+            json={"input_state": context or {}},
         )
+        result = response.get("execution_result")
+        return result if isinstance(result, dict) else response
 
     async def update(
         self,
@@ -1217,13 +1429,14 @@ class ProceduralResource(BaseResource):
         if description is not None:
             data["description"] = description
         if trigger_condition is not None:
-            data["trigger_condition"] = trigger_condition
+            data["condition"] = {"expression": trigger_condition}
         if action_sequence is not None:
-            data["action_sequence"] = action_sequence
+            data["action"] = {"steps": action_sequence}
         if metadata is not None:
-            data["metadata"] = metadata
+            data["parameters"] = metadata
 
-        return await self.client.patch(f"/procedural/{procedure_id}", json=data)
+        response = await self.client.patch(f"/v1/procedures/{procedure_id}", json=data)
+        return self._unwrap_procedure(response)
 
     async def delete(self, procedure_id: str) -> None:
         """
@@ -1232,7 +1445,7 @@ class ProceduralResource(BaseResource):
         Args:
             procedure_id: Procedure ID
         """
-        await self.client.delete(f"/procedural/{procedure_id}")
+        await self.client.delete(f"/v1/procedures/{procedure_id}")
 
 
 class TemporalResource(BaseResource):
@@ -1333,6 +1546,11 @@ class TemporalResource(BaseResource):
             },
         )
 
+    async def delete_fact(self, fact_id: str) -> Dict[str, Any]:
+        """Permanently delete a tenant-scoped temporal fact by stable ID."""
+
+        return await self.client.delete(f"/temporal/facts/{fact_id}")
+
 
 class WorkingMemoryResource(BaseResource):
     """Working memory buffer endpoints."""