hebbrix 2.3.2__tar.gz → 2.4.0__tar.gz

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

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

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: hebbrix
+Version: 2.4.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-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: 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.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, durable memory IDs, and status URL. Reuse the same idempotency key with
+the same body to recover the same logical resources.
+
+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.0/README.md

@@ -0,0 +1,98 @@
+# Hebbrix Python SDK
+
+Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
+
+## Install
+
+```bash
+pip install hebbrix==2.4.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, durable memory IDs, and status URL. Reuse the same idempotency key with
+the same body to recover the same logical resources.
+
+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.0/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.0"
+__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.0}/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.0",
         }
 
         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,

hebbrix-2.4.0/hebbrix/exceptions.py

@@ -0,0 +1,76 @@
+"""
+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."""
+
+    def __init__(self, message: str, receipt: dict):
+        self.receipt = dict(receipt)
+        self.memory_ids = list(receipt.get("memory_ids") or [])
+        self.status_url = receipt.get("status_url")
+        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)