hebbrix 2.3.0__tar.gz → 2.3.1__tar.gz

hebbrix-2.3.1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.3.0
+Version: 2.3.1
 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>
@@ -92,6 +92,10 @@ 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.
+
     # Search memories
     results = await client.search(
         query="What programming language does user like?",

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

@@ -51,6 +51,10 @@ 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.
+
     # Search memories
     results = await client.search(
         query="What programming language does user like?",

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

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

{hebbrix-2.3.0 → hebbrix-2.3.1}/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.1",
         }
 
         if self.api_key:

{hebbrix-2.3.0 → hebbrix-2.3.1}/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,99 @@ 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 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,
@@ -1333,6 +1429,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."""

{hebbrix-2.3.0 → hebbrix-2.3.1}/hebbrix/sync_client.py

@@ -1,7 +1,7 @@
 """Synchronous Hebbrix client for the core memory and ProofLoop lifecycle."""
 
-import os
 import json
+import os
 import time
 from typing import Any, Dict, List, Optional
 
@@ -65,6 +65,8 @@ class SyncMemoriesResource:
         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]:
         request_kwargs: Dict[str, Any] = {
             "json": _memory_create_payload(
@@ -90,7 +92,89 @@ class SyncMemoriesResource:
         }
         if idempotency_key:
             request_kwargs["headers"] = {"Idempotency-Key": idempotency_key}
-        return self.client.post("/v1/memories", **request_kwargs)
+        receipt = self.client.post("/v1/memories", **request_kwargs)
+        if wait_for_index:
+            receipt = self._ensure_searchable_receipt(
+                receipt,
+                timeout=index_timeout,
+                poll_interval=index_poll_interval,
+            )
+        return receipt
+
+    def wait_until_searchable(
+        self,
+        memory_id: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> Dict[str, Any]:
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            memory = 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"
+                )
+            time.sleep(max(0.05, poll_interval))
+
+    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:
+            job = SyncMemoryJobsResource(self.client).wait(
+                job_id,
+                timeout=timeout,
+                poll_interval=poll_interval,
+            )
+            if str(job.get("status") or "").casefold() != "completed":
+                raise RuntimeError(f"memory job {job_id} did not complete")
+            receipt.update(job)
+            receipt["searchable"] = True
+            receipt["processing_status"] = "completed"
+            return receipt
+        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 = 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
 
     def list_page(
         self,
@@ -460,7 +544,7 @@ class SyncMemoryClient:
         self.source = source or os.getenv("HEBBRIX_SOURCE")
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.3.0",
+            "User-Agent": "hebbrix-python/2.3.1",
         }
         if api_key:
             headers["Authorization"] = f"Bearer {api_key}"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.3.0
+Version: 2.3.1
 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>
@@ -92,6 +92,10 @@ 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.
+
     # Search memories
     results = await client.search(
         query="What programming language does user like?",

{hebbrix-2.3.0 → hebbrix-2.3.1}/hebbrix.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+CHANGELOG.md
 LICENSE
 MANIFEST.in
 README.md

{hebbrix-2.3.0 → hebbrix-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hebbrix"
-version = "2.3.0"
+version = "2.3.1"
 description = "Advanced Memory API for AI Agents with Reinforcement Learning - 3-line integration"
 readme = "README.md"
 requires-python = ">=3.8"

{hebbrix-2.3.0 → hebbrix-2.3.1}/tests/test_memories_resource.py

@@ -1,5 +1,6 @@
-import pytest
 from unittest.mock import AsyncMock
+
+import pytest
 from hebbrix.resources import (
     CorrectionsResource,
     MemoriesResource,
@@ -15,7 +16,11 @@ class RecordingClient:
 
     async def post(self, path, **kwargs):
         self.calls.append((path, kwargs))
-        return {"results": [{"id": "memory-1"}]}
+        return {
+            "results": [{"id": "memory-1"}],
+            "processing_status": "completed",
+            "searchable": True,
+        }
 
     async def get(self, path, **kwargs):
         self.calls.append((path, kwargs))
@@ -108,6 +113,75 @@ async def test_create_rejects_empty_content_before_network_io():
     assert client.calls == []
 
 
+@pytest.mark.asyncio
+async def test_wait_for_index_polls_until_the_memory_is_actually_searchable(
+    monkeypatch,
+):
+    client = RecordingClient()
+    states = iter(
+        [
+            {"id": "memory-1", "processing_status": "processing", "searchable": False},
+            {"id": "memory-1", "processing_status": "completed", "searchable": True},
+        ]
+    )
+
+    async def post(_path, **_kwargs):
+        return {
+            "results": [{"id": "memory-1"}],
+            "processing_status": "processing",
+            "searchable": False,
+        }
+
+    async def get(_path, **_kwargs):
+        return next(states)
+
+    client.post = post
+    client.get = get
+    monkeypatch.setattr("hebbrix.resources.asyncio.sleep", AsyncMock())
+
+    receipt = await MemoriesResource(client).create(
+        content="A fact",
+        wait_for_index=True,
+        index_timeout=2,
+        index_poll_interval=0.05,
+    )
+
+    assert receipt["searchable"] is True
+    assert receipt["processing_status"] == "completed"
+
+
+@pytest.mark.asyncio
+async def test_wait_for_index_never_returns_a_failed_terminal_state():
+    client = RecordingClient()
+
+    async def post(_path, **_kwargs):
+        return {
+            "results": [{"id": "memory-1"}],
+            "processing_status": "processing",
+            "searchable": False,
+        }
+
+    async def get(_path, **_kwargs):
+        return {"processing_status": "failed", "searchable": False}
+
+    client.post = post
+    client.get = get
+    with pytest.raises(RuntimeError, match="terminal state failed"):
+        await MemoriesResource(client).create(content="A fact", wait_for_index=True)
+
+
+@pytest.mark.asyncio
+async def test_wait_for_index_never_invents_searchability_from_completed_state():
+    client = RecordingClient()
+
+    async def get(_path, **_kwargs):
+        return {"processing_status": "completed", "searchable": False}
+
+    client.get = get
+    with pytest.raises(RuntimeError, match="completed without searchable=true"):
+        await MemoriesResource(client).wait_until_searchable("memory-1")
+
+
 @pytest.mark.asyncio
 async def test_create_supports_the_conversation_message_input_mode():
     client = RecordingClient()
@@ -261,6 +335,32 @@ async def test_search_sdk_fails_closed_when_safety_metadata_is_missing():
     assert response["sdk_safety_reason"].startswith("missing_safety_fields:")
 
 
+@pytest.mark.asyncio
+async def test_search_sdk_preserves_evidence_bound_degraded_results():
+    row = {"memory_id": "memory-1", "content": "exact fact", "score": 0.8}
+    client = SearchRecordingClient(
+        {
+            "results": [row],
+            "total": 1,
+            "no_match": False,
+            "abstain_recommended": True,
+            "query_confidence": 0.45,
+            "grounding": {"status": "degraded", "reason": "reranker_unavailable"},
+            "evidence_ids": ["memory-1"],
+            "evidence_claims": [],
+            "safety_contract_version": "search-safety-v1",
+            "degraded": True,
+        }
+    )
+
+    response = await SearchResource(client).search_with_proof("exact fact")
+
+    assert response["results"] == [row]
+    assert response["no_match"] is False
+    assert response["abstain_recommended"] is True
+    assert response["sdk_safety_reason"] == "degraded_evidence_preserved"
+
+
 @pytest.mark.asyncio
 async def test_reason_forwards_scopes_facets_and_preserves_safety_envelope():
     response = {

{hebbrix-2.3.0 → hebbrix-2.3.1}/tests/test_sync_client.py

@@ -12,7 +12,11 @@ class RecordingSyncClient:
 
     def post(self, path, **kwargs):
         self.calls.append(("POST", path, kwargs))
-        return {"decision_id": "decision-1"}
+        return {
+            "decision_id": "decision-1",
+            "processing_status": "completed",
+            "searchable": True,
+        }
 
     def get(self, path, **kwargs):
         self.calls.append(("GET", path, kwargs))