hebbrix 2.6.1__tar.gz → 2.6.2__tar.gz

{hebbrix-2.6.1 → hebbrix-2.6.2}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.6.2 — 2026-10-06 (compact advice, batches and confirmation)
+
+- Correct canonical documentation metadata and simplify the stable three-call guide.
+- Add optional compact search/advice, bounded independently committed decision/outcome batches, and explicit caller-confirmation transports.
+- Add bounded chat-learning wait options while preserving the original job receipt.
+- Keep historical confidence scope aliases, ACT-as-advice and protected outcome boundaries intact.
+- Requires matching Round9 server routes; no benchmark superiority, latency SLA or automatic execution is implied.
+
 ## 2.6.1 — 2026-10-04 (advisory horizon helpers)
 
 - Carry optional remaining_decisions and max_pilot_decisions through evidence reads and the once-only advisor callback.

{hebbrix-2.6.1/hebbrix.egg-info → hebbrix-2.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.6.1
+Version: 2.6.2
 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>
@@ -27,7 +27,7 @@ License: MIT License
         SOFTWARE.
         
 Project-URL: Homepage, https://hebbrix.com
-Project-URL: Documentation, https://docs.hebbrix.com
+Project-URL: Documentation, https://hebbrix.com/docs
 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
@@ -65,54 +65,23 @@ Dynamic: license-file
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-This branch is the **2.6.0 stable SDK**. The new policy configuration and
-advice helpers require backend schema `e5f6g7h8i868` or a compatible successor.
-A stable SDK does not qualify experimental learning or enable autonomous execution. ASK/REVIEW/ACT is advice;
-an action still requires independent permission.
+The current stable package is **2.6.2**. Start with memory storage and search, or
+the three-call outcome-learning workflow below. Advanced evidence and execution
+permission transports are opt-in; installing the SDK never permits an action.
 
 ## Install
 
 ```bash
-pip install hebbrix==2.6.0
+pip install hebbrix==2.6.2
 ```
 
 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,
+outcome-learning workflows; advanced temporal, working-memory, consolidation,
 memory-tool, and RL resources are currently async-only.
 
-The runtime requires `httpx>=0.25.0,<1`; incompatible 1.x prereleases are excluded.
-For the matching Round 5 backend, `setup_policy` accepts explicit `configuration`
-options for versioned change response and declared optional-field sharing, plus
-`value_objective={"success_value":10,"max_cost":20,"cost_unit":"USD"}`.
-Report both actual success and cost with `record_outcome`. Chat follow-up capture
-requires `features.learning: true` and an exact `outcome_followup.decision_id`;
-captured signals are provisional, not verified execution or autonomy evidence.
-These options require the matching runtime, not only the unchanged database schema.
-
 ## Quick start
 
-October 2 follow-up: `proofloop.setup_policy` atomically creates a new
-context/schema policy with explicitly declared low-risk exploration; existing
-policies are not migrated automatically. `learning_report` reads a bounded,
-scoped descriptive report, not proven uplift. `decide_with_advice` reads an
-evidence card, invokes the supplied advisor once and logs its actual choice and
-probabilities. `decide` accepts bounded `prior_action` / `prior_strength` for one
-server-selected decision; this is not outcome evidence. These new helpers and
-structured paraphrase matching require the matching October 2 outcome-followup
-backend, not merely its database schema; inspect `/v1/release` before use.
-Nothing here grants permission to execute. Learning performance and reliable
-model compliance with feedback are not established.
-
-Both clients expose `proofloop.register_context_schema`, `context_schema`,
-`configure_policy`, `policy_configuration`, `policy_advice` and `action_advice`.
-Enroll context before recording decisions. Configuration uses `expected_revision`
-for compare-and-swap; do not retry a conflict blindly. Exploration remains an
-explicit low-risk opt-in. `action_advice` takes the exact configured description,
-policy/action IDs and context, and maps `user_id` to the confidence endpoint's
-`end_user_id`. For the complete request shapes, see the
-[learning guide](https://www.hebbrix.com/docs/learning).
-
 ```python
 import asyncio
 from hebbrix import MemoryClient
@@ -135,6 +104,57 @@ async def main():
 asyncio.run(main())
 ```
 
+## Learn from outcomes in three calls
+
+Use server-side selection when Hebbrix should choose. Read-only advice is for a
+caller that intentionally chooses outside Hebbrix; an LLM can ignore that advice.
+Configure a new policy once, request a decision, then report its actual result:
+
+```python
+await client.proofloop.setup_policy(
+    "support.reply.v1", user_id="customer-42",
+    context_schema={"version": "v1", "fields": {
+        "issue": {"values": ["delivery", "billing"], "required": True}
+    }},
+    actions={
+        "explain": {"description": "Explain the delivery status", "target": "ticket",
+                    "risk_tier": "low", "exploration_allowed": True},
+        "review": {"description": "Request a support review", "target": "ticket",
+                   "risk_tier": "low", "exploration_allowed": True},
+    },
+    configuration={"strategy": "posterior_sampling"},
+)
+decision = await client.proofloop.decide(
+    policy_key="support.reply.v1", user_id="customer-42", mode="auto",
+    context={"issue": "delivery"},
+    candidates=[{"action_key": "explain"}, {"action_key": "review"}],
+    idempotency_key="ticket-42-decision",
+)
+# Your application checks permission and performs the action separately.
+# Here success is the actual result supplied by that application, not a prediction.
+await client.proofloop.record_outcome(
+    decision["decision_id"], success=success,
+    idempotency_key="ticket-42-result",
+)
+```
+
+`success` must come from your application or an independently authorized
+verifier. Do not report the recommendation itself as a successful execution.
+Keep action identities and required context stable. Use a new policy/version
+when changing what an action or outcome means. See the
+[recommended defaults](https://hebbrix.com/docs/learning).
+
+## Advice and integration boundaries
+
+`proofloop.action_advice(...)` reads the exact configured action and context.
+The canonical `gate` is `ASK`, `REVIEW`, `ACT`, or `BLOCK`. `BLOCK` dominates;
+`ACT` is advice, not permission. Apply your own current authorization and human
+approval policy before executing any tool. Do not infer permission from a score.
+
+Version 2.6.2 adds compact advice, batch, and explicit confirmation helpers.
+They require matching Round9 server routes. Compact views retain scope and safety
+caveats; complete receipts remain on the server.
+
 ## Durable readiness
 
 Memory writes return either a searchable completion or a durable `202` receipt.
@@ -215,7 +235,7 @@ 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)
+- [Documentation](https://hebbrix.com/docs)
 - [API reference](https://api.hebbrix.com/docs)
 - [PyPI files](https://pypi.org/project/hebbrix/#files)
 - [Support](https://www.hebbrix.com/contact)
@@ -223,14 +243,25 @@ The production API publishes exact build and artifact compatibility at
 ## License
 
 MIT. See `LICENSE` in the distribution.
-## Native experience workflow (prerelease)
+## Advanced evidence workflows
 
 The current source includes `client.experiences`, bounded reflection workers,
 separate lesson review/revision and explicit one-use execution admission. These
-methods require the matching new backend; the published 2.5.0 release does not
-include this extension. The candidate package supplies `hebbrix-reflect --help`.
+methods require the server's published compatibility contract and separately
+scoped credentials. The package supplies `hebbrix-reflect --help`.
 Importing it does not call a model, approve a lesson or execute a tool.
 
-See `docs/native-experience-operations.md` for role scopes,
+See the [documentation](https://hebbrix.com/docs) for role scopes,
 uncertain-call recovery, exact-request binding and policy rollback. Do not treat a
 lesson, score, review or issued permit as execution permission.
+
+## Stability
+
+Stable SDK versions follow semantic versioning. Patch updates correct defects;
+new optional fields and methods are additive. Existing required context, action
+identity, owner scope, and historical outcomes are not silently rewritten.
+Experimental APIs are marked separately. Security and correctness guards may
+be tightened immediately; migrations and other incompatible changes must be
+documented with their supported replacement. Read [CHANGELOG.md](CHANGELOG.md)
+before upgrading and pin versions in production. Release cadence is not a
+performance, compliance, or reliability guarantee.

{hebbrix-2.6.1 → hebbrix-2.6.2}/README.md

@@ -2,54 +2,23 @@
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-This branch is the **2.6.0 stable SDK**. The new policy configuration and
-advice helpers require backend schema `e5f6g7h8i868` or a compatible successor.
-A stable SDK does not qualify experimental learning or enable autonomous execution. ASK/REVIEW/ACT is advice;
-an action still requires independent permission.
+The current stable package is **2.6.2**. Start with memory storage and search, or
+the three-call outcome-learning workflow below. Advanced evidence and execution
+permission transports are opt-in; installing the SDK never permits an action.
 
 ## Install
 
 ```bash
-pip install hebbrix==2.6.0
+pip install hebbrix==2.6.2
 ```
 
 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,
+outcome-learning workflows; advanced temporal, working-memory, consolidation,
 memory-tool, and RL resources are currently async-only.
 
-The runtime requires `httpx>=0.25.0,<1`; incompatible 1.x prereleases are excluded.
-For the matching Round 5 backend, `setup_policy` accepts explicit `configuration`
-options for versioned change response and declared optional-field sharing, plus
-`value_objective={"success_value":10,"max_cost":20,"cost_unit":"USD"}`.
-Report both actual success and cost with `record_outcome`. Chat follow-up capture
-requires `features.learning: true` and an exact `outcome_followup.decision_id`;
-captured signals are provisional, not verified execution or autonomy evidence.
-These options require the matching runtime, not only the unchanged database schema.
-
 ## Quick start
 
-October 2 follow-up: `proofloop.setup_policy` atomically creates a new
-context/schema policy with explicitly declared low-risk exploration; existing
-policies are not migrated automatically. `learning_report` reads a bounded,
-scoped descriptive report, not proven uplift. `decide_with_advice` reads an
-evidence card, invokes the supplied advisor once and logs its actual choice and
-probabilities. `decide` accepts bounded `prior_action` / `prior_strength` for one
-server-selected decision; this is not outcome evidence. These new helpers and
-structured paraphrase matching require the matching October 2 outcome-followup
-backend, not merely its database schema; inspect `/v1/release` before use.
-Nothing here grants permission to execute. Learning performance and reliable
-model compliance with feedback are not established.
-
-Both clients expose `proofloop.register_context_schema`, `context_schema`,
-`configure_policy`, `policy_configuration`, `policy_advice` and `action_advice`.
-Enroll context before recording decisions. Configuration uses `expected_revision`
-for compare-and-swap; do not retry a conflict blindly. Exploration remains an
-explicit low-risk opt-in. `action_advice` takes the exact configured description,
-policy/action IDs and context, and maps `user_id` to the confidence endpoint's
-`end_user_id`. For the complete request shapes, see the
-[learning guide](https://www.hebbrix.com/docs/learning).
-
 ```python
 import asyncio
 from hebbrix import MemoryClient
@@ -72,6 +41,57 @@ async def main():
 asyncio.run(main())
 ```
 
+## Learn from outcomes in three calls
+
+Use server-side selection when Hebbrix should choose. Read-only advice is for a
+caller that intentionally chooses outside Hebbrix; an LLM can ignore that advice.
+Configure a new policy once, request a decision, then report its actual result:
+
+```python
+await client.proofloop.setup_policy(
+    "support.reply.v1", user_id="customer-42",
+    context_schema={"version": "v1", "fields": {
+        "issue": {"values": ["delivery", "billing"], "required": True}
+    }},
+    actions={
+        "explain": {"description": "Explain the delivery status", "target": "ticket",
+                    "risk_tier": "low", "exploration_allowed": True},
+        "review": {"description": "Request a support review", "target": "ticket",
+                   "risk_tier": "low", "exploration_allowed": True},
+    },
+    configuration={"strategy": "posterior_sampling"},
+)
+decision = await client.proofloop.decide(
+    policy_key="support.reply.v1", user_id="customer-42", mode="auto",
+    context={"issue": "delivery"},
+    candidates=[{"action_key": "explain"}, {"action_key": "review"}],
+    idempotency_key="ticket-42-decision",
+)
+# Your application checks permission and performs the action separately.
+# Here success is the actual result supplied by that application, not a prediction.
+await client.proofloop.record_outcome(
+    decision["decision_id"], success=success,
+    idempotency_key="ticket-42-result",
+)
+```
+
+`success` must come from your application or an independently authorized
+verifier. Do not report the recommendation itself as a successful execution.
+Keep action identities and required context stable. Use a new policy/version
+when changing what an action or outcome means. See the
+[recommended defaults](https://hebbrix.com/docs/learning).
+
+## Advice and integration boundaries
+
+`proofloop.action_advice(...)` reads the exact configured action and context.
+The canonical `gate` is `ASK`, `REVIEW`, `ACT`, or `BLOCK`. `BLOCK` dominates;
+`ACT` is advice, not permission. Apply your own current authorization and human
+approval policy before executing any tool. Do not infer permission from a score.
+
+Version 2.6.2 adds compact advice, batch, and explicit confirmation helpers.
+They require matching Round9 server routes. Compact views retain scope and safety
+caveats; complete receipts remain on the server.
+
 ## Durable readiness
 
 Memory writes return either a searchable completion or a durable `202` receipt.
@@ -152,7 +172,7 @@ 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)
+- [Documentation](https://hebbrix.com/docs)
 - [API reference](https://api.hebbrix.com/docs)
 - [PyPI files](https://pypi.org/project/hebbrix/#files)
 - [Support](https://www.hebbrix.com/contact)
@@ -160,14 +180,25 @@ The production API publishes exact build and artifact compatibility at
 ## License
 
 MIT. See `LICENSE` in the distribution.
-## Native experience workflow (prerelease)
+## Advanced evidence workflows
 
 The current source includes `client.experiences`, bounded reflection workers,
 separate lesson review/revision and explicit one-use execution admission. These
-methods require the matching new backend; the published 2.5.0 release does not
-include this extension. The candidate package supplies `hebbrix-reflect --help`.
+methods require the server's published compatibility contract and separately
+scoped credentials. The package supplies `hebbrix-reflect --help`.
 Importing it does not call a model, approve a lesson or execute a tool.
 
-See `docs/native-experience-operations.md` for role scopes,
+See the [documentation](https://hebbrix.com/docs) for role scopes,
 uncertain-call recovery, exact-request binding and policy rollback. Do not treat a
 lesson, score, review or issued permit as execution permission.
+
+## Stability
+
+Stable SDK versions follow semantic versioning. Patch updates correct defects;
+new optional fields and methods are additive. Existing required context, action
+identity, owner scope, and historical outcomes are not silently rewritten.
+Experimental APIs are marked separately. Security and correctness guards may
+be tightened immediately; migrations and other incompatible changes must be
+documented with their supported replacement. Read [CHANGELOG.md](CHANGELOG.md)
+before upgrading and pin versions in production. Release cadence is not a
+performance, compliance, or reliability guarantee.

{hebbrix-2.6.1 → hebbrix-2.6.2}/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.6.1"
+__version__ = "2.6.2"
 __author__ = "Hebbrix Team"
 __license__ = "MIT"
 
@@ -21,7 +21,7 @@ from hebbrix.exceptions import (
     ServerError,
     ValidationError,
 )
-from hebbrix.models import EvidenceClaim, GroundingReceipt, SearchSafetyEnvelope
+from hebbrix.models import ActionAdviceReceipt, EvidenceClaim, GroundingReceipt, SearchSafetyEnvelope
 from hebbrix.sync_client import SyncMemoryClient
 
 __all__ = [
@@ -39,4 +39,5 @@ __all__ = [
     "GroundingReceipt",
     "EvidenceClaim",
     "SearchSafetyEnvelope",
+    "ActionAdviceReceipt",
 ]

{hebbrix-2.6.1 → hebbrix-2.6.2}/hebbrix/_advice.py

@@ -5,6 +5,54 @@ import math
 import re
 
 
+def _validate_advice_view(view):
+    if view is not None and view not in ("full", "compact"):
+        raise ValueError("view must be full or compact")
+
+
+def _confirmation_payload(observation_id, idempotency_key, success, confirmed,
+                          collection_id=None, user_id=None, source_system=None,
+                          source_event_id=None, evidence_digest=None):
+    if type(success) is not bool or confirmed is not True:
+        raise ValueError("explicit Boolean success and confirmed=True are required")
+    for field, value in (("observation_id", observation_id),
+                         ("idempotency_key", idempotency_key)):
+        if type(value) is not str or not value.strip() or len(value) > 160:
+            raise ValueError("{} must be a nonempty bounded string".format(field))
+    return {key: value for key, value in dict(
+        observation_id=observation_id, idempotency_key=idempotency_key,
+        success=success, confirmed=True, collection_id=collection_id, user_id=user_id,
+        source_system=source_system, source_event_id=source_event_id,
+        evidence_digest=evidence_digest,
+    ).items() if value is not None}
+
+
+def _batch_payload(items, view="compact", outcomes=False):
+    _validate_advice_view(view)
+    if type(items) is not list or not 1 <= len(items) <= 50:
+        raise ValueError("batch items must contain 1-50 requests")
+    copied = _json_snapshot(items, "batch items", 4_000_000)
+    for item in copied:
+        if type(item) is not dict:
+            raise ValueError("each batch item must be an object")
+        key = item.get("idempotency_key")
+        if type(key) is not str or not key.strip() or len(key) > 160:
+            raise ValueError("each batch item needs a nonempty idempotency_key")
+        if outcomes and (type(item.get("decision_id")) is not str or
+                         not item["decision_id"].strip() or
+                         type(item.get("outcome")) is not dict):
+            raise ValueError("outcome items need decision_id and an outcome object")
+        if not outcomes and "proof_context" in item:
+            context = item.pop("proof_context")
+            token = context.get("token") if type(context) is dict else context
+            if type(token) is not str or not token.strip():
+                raise ValueError("proof_context must contain the original proof token")
+            if "proof_context_token" in item and item["proof_context_token"] != token:
+                raise ValueError("conflicting proof context tokens")
+            item["proof_context_token"] = token
+    return {"items": copied, **({"view": view} if view is not None else {})}
+
+
 def _validate_advisor_horizon(remaining_decisions, max_pilot_decisions):
     for field, value, maximum in (("remaining_decisions", remaining_decisions, 10000),
                                   ("max_pilot_decisions", max_pilot_decisions, 8)):

{hebbrix-2.6.1 → hebbrix-2.6.2}/hebbrix/chat.py

@@ -11,11 +11,27 @@ Example:
 """
 
 from typing import Any, Dict, List, Optional
+import math
 
 import requests
 from hebbrix.client import MemoryClient
 
 
+def _chat_readiness_options(wait_for_learning_seconds, include_low_confidence):
+    if (isinstance(wait_for_learning_seconds, bool) or
+        not isinstance(wait_for_learning_seconds, (int, float)) or
+        not math.isfinite(wait_for_learning_seconds) or
+        not 0 <= wait_for_learning_seconds <= 20):
+        raise ValueError("wait_for_learning_seconds must be between 0 and 20")
+    if type(include_low_confidence) is not bool:
+        raise ValueError("include_low_confidence must be explicitly Boolean")
+    return {
+        **({"wait_for_learning_seconds": wait_for_learning_seconds}
+           if wait_for_learning_seconds else {}),
+        **({"include_low_confidence": True} if include_low_confidence else {}),
+    }
+
+
 class MemoryChat:
     """
     Simple chat interface with automatic memory integration.
@@ -94,6 +110,8 @@ class MemoryChat:
         session_id: str,
         temperature: float = 0.7,
         max_tokens: Optional[int] = None,
+        *, wait_for_learning_seconds: float = 0,
+        include_low_confidence: bool = False,
     ) -> str:
         """
         Send a message and get a response with automatic memory integration.
@@ -122,6 +140,7 @@ class MemoryChat:
             "prompt_strategy": self.prompt_strategy,
             "memory_limit": self.memory_limit,
             "temperature": temperature,
+            **_chat_readiness_options(wait_for_learning_seconds, include_low_confidence),
         }
 
         if max_tokens:
@@ -146,6 +165,8 @@ class MemoryChat:
         session_id: str,
         temperature: float = 0.7,
         max_tokens: Optional[int] = None,
+        *, wait_for_learning_seconds: float = 0,
+        include_low_confidence: bool = False,
     ) -> Dict[str, Any]:
         """
         Send a message and get full response with memory context.
@@ -176,6 +197,7 @@ class MemoryChat:
             "prompt_strategy": self.prompt_strategy,
             "memory_limit": self.memory_limit,
             "temperature": temperature,
+            **_chat_readiness_options(wait_for_learning_seconds, include_low_confidence),
         }
 
         if max_tokens:

{hebbrix-2.6.1 → hebbrix-2.6.2}/hebbrix/client.py

@@ -93,7 +93,7 @@ class MemoryClient:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.6.1",
+            "User-Agent": "hebbrix-python/2.6.2",
         }
 
         if self.api_key:
@@ -254,6 +254,7 @@ class MemoryClient:
         include_low_confidence: bool = False,
         group_by_source: bool = True,
         debug: bool = False,
+        view: Optional[str] = None,
     ) -> List[Dict[str, Any]]:
         """
         Search memories.
@@ -282,6 +283,7 @@ class MemoryClient:
             include_low_confidence=include_low_confidence,
             group_by_source=group_by_source,
             debug=debug,
+            view=view,
         )
 
     async def search_with_proof(
@@ -299,6 +301,7 @@ class MemoryClient:
         include_low_confidence: bool = False,
         group_by_source: bool = True,
         debug: bool = False,
+        view: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Search and return both results and the automatic ProofLoop context."""
 
@@ -316,6 +319,7 @@ class MemoryClient:
             include_low_confidence=include_low_confidence,
             group_by_source=group_by_source,
             debug=debug,
+            view=view,
         )
 
     async def reason(

{hebbrix-2.6.1 → hebbrix-2.6.2}/hebbrix/models.py

@@ -1,6 +1,21 @@
 """Public response contracts for evidence-bearing Hebbrix operations."""
 
-from typing import Any, Dict, List, TypedDict
+from typing import Any, Dict, List, TypedDict, Literal, Optional
+
+
+class ActionAdviceReceipt(TypedDict, total=False):
+    """Canonical advice envelope. ACT is never execution authorization."""
+
+    gate: Literal["ASK", "REVIEW", "ACT", "BLOCK"]
+    recommendation: str
+    recommended_action: str
+    action_confidence: Optional[float]
+    blocked_by: Optional[str]
+    blocked_hint: Optional[str]
+    autonomy_evidence: Dict[str, Any]
+    action_evidence: List[Dict[str, Any]]
+    authorization_granted: bool
+    execution_permission_required: bool
 
 
 class GroundingReceipt(TypedDict, total=False):