hebbrix 2.6.0rc5__tar.gz → 2.6.2__tar.gz

{hebbrix-2.6.0rc5 → hebbrix-2.6.2}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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.
+- Keep actual caller distribution validation, owner scope and observe-mode logging unchanged.
+- New backend v3 controls remain explicit experimental opt-ins; these helpers do not execute actions or establish performance, calibration or superiority.
+
+## 2.6.0 — 2026-10-04 (stable SDK)
+
+- Bound runtime HTTPX to `>=0.25.0,<1`, excluding incompatible 1.x prereleases.
+- Add sync/async atomic setup options for explicit policy configuration and built-in success-minus-cost metrics.
+- Keep advisor input/probability validation, scope and protected evidence transports unchanged.
+- Backend v3 learning methods remain explicit experimental opt-ins. Stable packaging does not establish performance, calibrated confidence or execution permission.
+
 ## 2.6.0rc5 — 2026-10-03 (prerelease)
 
 - Snapshot advisor context/candidates and reject scope overrides or mutable identities.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.6.0rc5
+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,13 +27,13 @@ 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
 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: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
@@ -49,7 +49,7 @@ Classifier: Framework :: AsyncIO
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx>=0.25.0
+Requires-Dist: httpx<1,>=0.25.0
 Requires-Dist: requests>=2.31.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
@@ -65,45 +65,23 @@ Dynamic: license-file
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-This branch is the **2.6.0rc2 prerelease**. The new policy configuration and
-advice helpers require backend schema `e5f6g7h8i868` or a compatible successor.
-A prerelease SDK does not 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.0rc2
+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.
 
 ## 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
@@ -126,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.
@@ -206,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)
@@ -214,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.0rc5 → hebbrix-2.6.2}/README.md

@@ -2,45 +2,23 @@
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-This branch is the **2.6.0rc2 prerelease**. The new policy configuration and
-advice helpers require backend schema `e5f6g7h8i868` or a compatible successor.
-A prerelease SDK does not 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.0rc2
+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.
 
 ## 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
@@ -63,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.
@@ -143,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)
@@ -151,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.0rc5 → 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.0rc5"
+__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.0rc5 → hebbrix-2.6.2}/hebbrix/_advice.py

@@ -5,6 +5,61 @@ 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)):
+        if value is not None and (type(value) is not int or not 1 <= value <= maximum):
+            raise ValueError("{} must be an integer within the API limit".format(field))
+
+
 def _validate_advisor_scope(policy_key, collection_id, user_id, idempotency_key):
     if (
         type(policy_key) is not str

{hebbrix-2.6.0rc5 → 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.0rc5 → 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.0rc5",
+            "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.0rc5 → 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):