hebbrix 2.7.0__tar.gz → 2.8.0__tar.gz

{hebbrix-2.7.0 → hebbrix-2.8.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.8.0 — 2026-11-11 (answer decisions and answer context)
+
+- New `hebbrix.should_answer(response)`: decides in code whether a `search_with_proof()` or `reason()` response may be answered from, returning an `AnswerDecision` with `action` (`answer`, `say_unknown`, `abstain`, `verify_authorization`, `ask_user`, `retry` or `say_no_longer_current`), `reason`, the usable `memories` and the `context` rows never to answer from. `history=True` counts superseded and historical versions for questions about the past.
+- New `hebbrix.answer_context(response, decision)`: renders the end user's standing profile (facts with category, confidence and date, topics to avoid, scope, and whether it is still being projected or unavailable) beside the rows the decision allows, each with its date, memory type, subject and support.
+- New `hebbrix.usable_memories(response)` and the response types `AnswerStatus`, `RevisionStatus`, `MemoryRow`, `MemoryStatus` and `ScopeIndexing`.
+- `MemoryClient.search_with_proof()` accepts `include_profile` and `include_superseded`, as the synchronous client and `search()` already did.
+- Docs: `memories.create()` stores verbatim unless `infer=True`, while `POST /v1/memories` extracts by default; examples pass `infer` and `wait_for_index` explicitly.
+
 ## 2.7.0 — 2026-10-19 (compact responses, entity scope, chat answers)
 
 - Behaviour change: `search()` and `search_with_proof()` now request `view="compact"` by default (rows keep content, identity, score, rank, timestamps, `low_confidence` and entity scope; the safety envelope and proof context are unchanged; ranking diagnostics need `debug=True`). Pass `view="full"` for the previous per-row metadata. `search()` returns rows only and no longer requests the unused ProofLoop token unless `include_proof_context=True`.

{hebbrix-2.7.0/hebbrix.egg-info → hebbrix-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.7.0
+Version: 2.8.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>
@@ -65,14 +65,14 @@ Dynamic: license-file
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-The current stable package is **2.7.0**. Start with memory storage and search, or
+The current stable package is **2.8.0**. 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.7.0
+pip install hebbrix==2.8.0
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -92,7 +92,8 @@ async def main():
         memory = await client.memories.create(
             collection_id=collection["id"],
             content="Customer prefers concise replies",
-            wait_for_index=True,
+            infer=False,  # store verbatim (the SDK default; REST defaults to True)
+            wait_for_index=True,  # return once it is searchable
             idempotency_key="customer-42-preference-v1",
         )
         results = await client.search(
@@ -104,6 +105,51 @@ async def main():
 asyncio.run(main())
 ```
 
+> **`memories.create()` and `POST /v1/memories` have different defaults.** The
+> SDK stores the content verbatim as one memory unless you pass `infer=True`;
+> the REST endpoint called without `infer` extracts facts with the server's
+> language model (`infer` defaults to `true` there). Pass `infer` and
+> `wait_for_index` explicitly, as above, so a call reads the same through the
+> SDK and over HTTP. Use `infer=True` (or `/v1/memories/process`) for
+> conversations; `infer=False` for a fact you already have in final form.
+
+## Decide before you invoke your model
+
+A model told to abstain can still answer. Decide in code, and give it only the rows
+that passed. `search()` returns only the rows, so use `search_with_proof()` or
+`reason()`, which keep the fields this reads:
+
+```python
+from hebbrix import answer_context, should_answer
+
+response = await client.search_with_proof(
+    question, user_id="customer-42", include_profile=True
+)
+decision = should_answer(response)
+if not decision:
+    # decision.action: ask_user, say_no_longer_current, say_unknown, retry,
+    # verify_authorization or abstain. decision.reason says why;
+    # decision.context holds the rows, never to answer from.
+    return my_reply_for(decision.action)
+# The user's standing profile plus the rows you may answer from, each with its
+# date, memory type, subject and support.
+return await my_llm(question, context=answer_context(response, decision))
+```
+
+`answer_context(response, decision)` keeps the end user's standing profile
+(`include_profile=True`) beside the rows: preferences such as "keep answers
+short" reach your model even when they did not rank for this message. It lists
+each fact with its category, confidence and date, the topics to avoid, the
+profile's `scope`, and says so when the profile is still being updated
+(`projection.status: "pending"`) or could not be read, so a missing preference
+is not taken as absent. When the decision is not to answer it returns the
+profile alone. `usable_memories(response)` returns just the rows. Pass
+`history=True` for a question about the past, when superseded and historical
+versions should count. `reason()` takes `deadline_ms`; a `timed_out` response is
+an abstention. `verify_authorization` means the returned rule limits the action
+to a group the store cannot place the user in: use the rule, and check the
+permission in your own system.
+
 ## Learn from outcomes in three calls
 
 Use server-side selection when Hebbrix should choose. Read-only advice is for a
@@ -191,6 +237,7 @@ from hebbrix import IndexingTimeoutError
 try:
     created = await client.memories.create(
         content="Customer prefers concise replies",
+        infer=False,
         wait_for_index=True,
         idempotency_key="customer-42-preference-v1",
         index_timeout=5,

{hebbrix-2.7.0 → hebbrix-2.8.0}/README.md

@@ -2,14 +2,14 @@
 
 Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 
-The current stable package is **2.7.0**. Start with memory storage and search, or
+The current stable package is **2.8.0**. 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.7.0
+pip install hebbrix==2.8.0
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -29,7 +29,8 @@ async def main():
         memory = await client.memories.create(
             collection_id=collection["id"],
             content="Customer prefers concise replies",
-            wait_for_index=True,
+            infer=False,  # store verbatim (the SDK default; REST defaults to True)
+            wait_for_index=True,  # return once it is searchable
             idempotency_key="customer-42-preference-v1",
         )
         results = await client.search(
@@ -41,6 +42,51 @@ async def main():
 asyncio.run(main())
 ```
 
+> **`memories.create()` and `POST /v1/memories` have different defaults.** The
+> SDK stores the content verbatim as one memory unless you pass `infer=True`;
+> the REST endpoint called without `infer` extracts facts with the server's
+> language model (`infer` defaults to `true` there). Pass `infer` and
+> `wait_for_index` explicitly, as above, so a call reads the same through the
+> SDK and over HTTP. Use `infer=True` (or `/v1/memories/process`) for
+> conversations; `infer=False` for a fact you already have in final form.
+
+## Decide before you invoke your model
+
+A model told to abstain can still answer. Decide in code, and give it only the rows
+that passed. `search()` returns only the rows, so use `search_with_proof()` or
+`reason()`, which keep the fields this reads:
+
+```python
+from hebbrix import answer_context, should_answer
+
+response = await client.search_with_proof(
+    question, user_id="customer-42", include_profile=True
+)
+decision = should_answer(response)
+if not decision:
+    # decision.action: ask_user, say_no_longer_current, say_unknown, retry,
+    # verify_authorization or abstain. decision.reason says why;
+    # decision.context holds the rows, never to answer from.
+    return my_reply_for(decision.action)
+# The user's standing profile plus the rows you may answer from, each with its
+# date, memory type, subject and support.
+return await my_llm(question, context=answer_context(response, decision))
+```
+
+`answer_context(response, decision)` keeps the end user's standing profile
+(`include_profile=True`) beside the rows: preferences such as "keep answers
+short" reach your model even when they did not rank for this message. It lists
+each fact with its category, confidence and date, the topics to avoid, the
+profile's `scope`, and says so when the profile is still being updated
+(`projection.status: "pending"`) or could not be read, so a missing preference
+is not taken as absent. When the decision is not to answer it returns the
+profile alone. `usable_memories(response)` returns just the rows. Pass
+`history=True` for a question about the past, when superseded and historical
+versions should count. `reason()` takes `deadline_ms`; a `timed_out` response is
+an abstention. `verify_authorization` means the returned rule limits the action
+to a group the store cannot place the user in: use the rule, and check the
+permission in your own system.
+
 ## Learn from outcomes in three calls
 
 Use server-side selection when Hebbrix should choose. Read-only advice is for a
@@ -128,6 +174,7 @@ from hebbrix import IndexingTimeoutError
 try:
     created = await client.memories.create(
         content="Customer prefers concise replies",
+        infer=False,
         wait_for_index=True,
         idempotency_key="customer-42-preference-v1",
         index_timeout=5,

{hebbrix-2.7.0 → hebbrix-2.8.0}/hebbrix/__init__.py

@@ -5,10 +5,16 @@ production OpenAPI and ``GET /v1/users/me/capabilities``. The experimental
 World Model is intentionally absent from this release.
 """
 
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 __author__ = "Hebbrix Team"
 __license__ = "MIT"
 
+from hebbrix.answers import (
+    AnswerDecision,
+    answer_context,
+    should_answer,
+    usable_memories,
+)
 from hebbrix.chat import MemoryChat
 from hebbrix.client import MemoryClient
 from hebbrix.exceptions import (
@@ -21,7 +27,17 @@ from hebbrix.exceptions import (
     ServerError,
     ValidationError,
 )
-from hebbrix.models import ActionAdviceReceipt, EvidenceClaim, GroundingReceipt, SearchSafetyEnvelope
+from hebbrix.models import (
+    ActionAdviceReceipt,
+    AnswerStatus,
+    EvidenceClaim,
+    GroundingReceipt,
+    MemoryRow,
+    MemoryStatus,
+    RevisionStatus,
+    ScopeIndexing,
+    SearchSafetyEnvelope,
+)
 from hebbrix.sync_client import SyncMemoryClient
 
 __all__ = [
@@ -40,4 +56,13 @@ __all__ = [
     "EvidenceClaim",
     "SearchSafetyEnvelope",
     "ActionAdviceReceipt",
+    "AnswerDecision",
+    "AnswerStatus",
+    "MemoryRow",
+    "MemoryStatus",
+    "RevisionStatus",
+    "ScopeIndexing",
+    "answer_context",
+    "should_answer",
+    "usable_memories",
 ]

hebbrix-2.8.0/hebbrix/answers.py

@@ -0,0 +1,316 @@
+"""Decide in code what a search or Reason response lets you do.
+
+A model that is told "abstain_recommended: true" can still answer. Call
+``should_answer`` before invoking the model and give it only
+``decision.memories``: when the decision is not to answer, the model is never
+called, so it cannot ignore the flag.
+
+    response = await client.search_with_proof(
+        question, user_id=user_id, include_profile=True
+    )
+    decision = should_answer(response)
+    if not decision:
+        return reply_for(decision.action)  # your own fixed reply per action
+    return await my_llm(question, context=answer_context(response, decision))
+
+``answer_context`` renders the end user's standing profile beside those rows,
+so a preference that did not rank for this message still reaches the model.
+
+``search()`` returns only the rows, without the fields this needs; use
+``search_with_proof()`` or ``reason()``. The decision is derived from the
+response alone: nothing here calls the API, and it fails closed on a response it
+does not understand.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+ANSWER_STATUSES = (
+    "answerable",
+    "conflicting",
+    "superseded",
+    "unverified",
+    "indexing",
+    "no_relevant_memory",
+)
+REVISION_STATUSES = ("current", "superseded", "conflicting", "historical")
+
+# What to do instead of answering, for each ``answer_status``.
+ACTIONS = {
+    "answerable": "answer",
+    "conflicting": "ask_user",
+    "superseded": "say_no_longer_current",
+    "unverified": "abstain",
+    "indexing": "retry",
+    "no_relevant_memory": "say_unknown",
+}
+# A permission question answered by a rule that restricts the act to a group no
+# memory ties the asker to (``confidence_reason`` "authorization_not_verifiable"):
+# the rule is in ``context``; check the asker's role in your own system.
+AUTHORIZATION_NOT_VERIFIABLE = "authorization_not_verifiable"
+VERIFY_AUTHORIZATION = "verify_authorization"
+# Set by the SDK on a response whose rows it kept although it is degraded: not a
+# malformed envelope, so it is not a reason to fail closed on its own.
+_PRESERVED = "degraded_evidence_preserved"
+_PAST = frozenset({"superseded", "historical"})
+
+
+@dataclass(frozen=True)
+class AnswerDecision:
+    """What a response lets you do; true only when you may answer from it."""
+
+    answer: bool
+    reason: str
+    action: str
+    # Safe to pass to a model as evidence; empty unless ``answer`` is true.
+    memories: List[Dict[str, Any]] = field(default_factory=list)
+    # The other rows returned, each with its revision_status and low_confidence:
+    # to show or to ask about ("which of these holds?"), never to answer from.
+    context: List[Dict[str, Any]] = field(default_factory=list)
+    # Reason only: context for a decision it could not verify, with citations.
+    cited_context: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        return self.answer
+
+
+def _rows(response: Mapping[str, Any]) -> Tuple[List[Dict[str, Any]], bool]:
+    """The response's rows, and whether they are search rows (which always say
+    ``low_confidence``) rather than Reason's cited sources."""
+
+    results = response.get("results")
+    if isinstance(results, list):
+        return [row for row in results if isinstance(row, dict)], True
+    sources = response.get("sources")
+    if isinstance(sources, list):
+        return [row for row in sources if isinstance(row, dict)], False
+    return [], False
+
+
+def _is_evidence(row: Mapping[str, Any], *, search_row: bool) -> bool:
+    """A current row established as evidence. A row that does not say so is not."""
+
+    if row.get("revision_status") != "current" or row.get("is_current") is False:
+        return False
+    confidence = row.get("low_confidence")
+    return confidence is False if search_row else confidence is not True
+
+
+def _is_history(row: Mapping[str, Any], *, search_row: bool) -> bool:
+    """A row a question about the past may read: an earlier version, labelled as
+    one (the server flags those low_confidence for the present), or evidence."""
+
+    return row.get("revision_status") in _PAST or _is_evidence(
+        row, search_row=search_row
+    )
+
+
+def should_answer(
+    response: Optional[Mapping[str, Any]], *, history: bool = False
+) -> AnswerDecision:
+    """Whether you may answer from ``response`` (a ``search_with_proof`` or
+    ``reason`` result), the rows to answer from, and what to do when you may not.
+
+    ``history=True`` is for a question about the past that your application
+    recognises ("Where did I live before?"): superseded and historical rows then
+    count, whatever the response says of the present. Keep each row's
+    ``revision_status`` and ``stated_at`` in what you pass to the model, so it can
+    tell the versions apart. Conflicting rows never count.
+    """
+
+    if not isinstance(response, Mapping) or "answer_status" not in response:
+        return AnswerDecision(False, "unsupported_response", "abstain")
+    status = response.get("answer_status")
+    safety = response.get("sdk_safety_reason")
+    if status not in ANSWER_STATUSES or (safety and safety != _PRESERVED):
+        return AnswerDecision(False, "malformed_response", "abstain")
+    rows, search_rows = _rows(response)
+    cited = response.get("cited_context")
+    cited = cited if isinstance(cited, str) and cited else None
+
+    def declined(reason: str, action: str) -> AnswerDecision:
+        return AnswerDecision(False, reason, action, [], rows, cited)
+
+    if status == "conflicting":
+        return declined(status, ACTIONS[status])
+    if response.get("confidence_reason") == AUTHORIZATION_NOT_VERIFIABLE:
+        return declined(AUTHORIZATION_NOT_VERIFIABLE, VERIFY_AUTHORIZATION)
+    if history:
+        usable = [row for row in rows if _is_history(row, search_row=search_rows)]
+        if usable:
+            others = [row for row in rows if row not in usable]
+            return AnswerDecision(True, "history", "answer", usable, others, cited)
+    if status != "answerable":
+        return declined(status, ACTIONS[status])
+    for flag in ("no_match", "abstain_recommended", "decision_abstained"):
+        if response.get(flag) is True:
+            return declined(flag, "abstain")
+    usable = [row for row in rows if _is_evidence(row, search_row=search_rows)]
+    if not usable:
+        return declined("no_usable_memories", "abstain")
+    others = [row for row in rows if row not in usable]
+    return AnswerDecision(True, status, "answer", usable, others, cited)
+
+
+def usable_memories(
+    response: Optional[Mapping[str, Any]], *, history: bool = False
+) -> List[Dict[str, Any]]:
+    """The rows of ``response`` safe to pass to a model as evidence; empty when
+    ``should_answer`` says not to answer."""
+
+    return should_answer(response, history=history).memories
+
+
+def _day(value: Any) -> Optional[str]:
+    """The calendar date of an ISO timestamp (the API's dates are ISO 8601)."""
+
+    return str(value)[:10] if isinstance(value, str) and value else None
+
+
+def _count(value: Any) -> int:
+    try:
+        return int(float(value or 0))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _profile_lines(profile: Any) -> List[str]:
+    if not isinstance(profile, Mapping):
+        return []
+    if profile.get("status") != "ok":
+        # Unreadable is not empty: a preference may exist that was not returned.
+        return ["Standing profile of this user: unavailable for this request."]
+    facts = [
+        fact
+        for fact in profile.get("facts") or []
+        if isinstance(fact, Mapping) and fact.get("value") not in (None, "")
+    ]
+    avoid = [t for t in profile.get("avoid_topics") or [] if isinstance(t, str) and t]
+    projection = profile.get("projection")
+    projection = projection if isinstance(projection, Mapping) else {}
+    pending = projection.get("status") == "pending"
+    if not facts and not avoid and not pending:
+        return []
+    scope = profile.get("scope")
+    scope = (
+        scope
+        if isinstance(scope, Mapping)
+        else {"end_user_id": profile.get("end_user_id")}
+    )
+    details = [f"{key} {value}" for key, value in scope.items() if value]
+    if _day(profile.get("as_of")):
+        details.append(f"as of {_day(profile.get('as_of'))}")
+    if projection.get("status"):
+        details.append(f"projection {projection['status']}")
+    header = "Standing profile of this user (applies to every reply"
+    lines = [header + ("; " + "; ".join(details) if details else "") + "):"]
+    for fact in facts:
+        name = " / ".join(str(fact[k]) for k in ("category", "key") if fact.get(k))
+        meta = []
+        if isinstance(fact.get("confidence"), (int, float)):
+            meta.append(f"confidence {float(fact['confidence']):.2f}")
+        if _day(fact.get("updated_at")):
+            meta.append(f"updated {_day(fact.get('updated_at'))}")
+        text = f"{name}: {fact['value']}" if name else str(fact["value"])
+        lines.append(f"- {text}" + (f" ({', '.join(meta)})" if meta else ""))
+    if avoid:
+        lines.append("- avoid topics: " + ", ".join(avoid))
+    if pending:
+        count = projection.get("pending_writes")
+        writes = (
+            f"{'at least ' if projection.get('capped') else ''}{count} recent writes"
+            if isinstance(count, int) and count > 0
+            else "recent writes"
+        )
+        lines.append(
+            f"- still being updated: {writes} not yet reflected; a fact here may be "
+            "missing or about to change."
+        )
+    return lines
+
+
+def _memory_details(row: Mapping[str, Any]) -> List[str]:
+    metadata = row.get("metadata") if isinstance(row.get("metadata"), Mapping) else {}
+    details = []
+    memory_type = metadata.get("memory_type") or row.get("memory_type")
+    if memory_type:
+        details.append(str(memory_type))
+    if _day(row.get("stated_at")):
+        details.append(f"stated {_day(row.get('stated_at'))}")
+    elif _day(row.get("created_at")):
+        details.append(f"saved {_day(row.get('created_at'))}")
+    if _day(row.get("valid_until")):
+        details.append(f"valid until {_day(row.get('valid_until'))}")
+    if row.get("subject"):
+        details.append(f"about {row['subject']}")
+    applies_to = row.get("applies_to")
+    names = (
+        [n for n in applies_to if isinstance(n, str) and n]
+        if isinstance(applies_to, list)
+        else []
+    )
+    if names:
+        details.append("names " + ", ".join(names))
+    if row.get("revision_status"):
+        details.append(str(row["revision_status"]))
+    grounding = row.get("grounding")
+    if not isinstance(grounding, Mapping):
+        grounding = metadata.get("grounding")
+    if isinstance(grounding, Mapping):
+        support = grounding.get("support_basis") or grounding.get("status")
+        if support:
+            details.append(f"support {support}")
+    outcomes = metadata.get("outcome_evidence")
+    if isinstance(outcomes, Mapping) and (
+        outcomes.get("successes") or outcomes.get("failures")
+    ):
+        details.append(
+            f"outcomes {_count(outcomes.get('successes'))} worked, "
+            f"{_count(outcomes.get('failures'))} failed"
+        )
+    return details
+
+
+def answer_context(
+    response: Optional[Mapping[str, Any]],
+    decision: Optional[AnswerDecision] = None,
+    *,
+    history: bool = False,
+) -> str:
+    """The text to give your own model with the user's message: the end user's
+    standing profile and the memories ``should_answer`` lets you answer from.
+
+    Pass a ``search_with_proof(..., include_profile=True)`` or ``reason()``
+    response, and the decision you already made on it (computed here when
+    omitted). The profile section lists each standing fact with its category,
+    confidence and date, the topics to avoid, the profile's scope, and whether
+    it is still being projected from recent writes; an unavailable profile is
+    said to be unavailable, never left out as if empty. The memories section
+    lists only ``decision.memories``, numbered for citation, each with its
+    memory type, date, whom it is about, the names it states, its revision
+    status and its support. When the decision is not to answer, only the
+    profile is returned: standing preferences still shape a reply such as
+    "I don't know that yet". Returns "" when there is nothing to add.
+    """
+
+    if decision is None:
+        decision = should_answer(response, history=history)
+    sections = []
+    profile = _profile_lines(
+        response.get("profile") if isinstance(response, Mapping) else None
+    )
+    if profile:
+        sections.append("\n".join(profile))
+    if decision.answer and decision.memories:
+        heading = (
+            "Memories to answer from (earlier versions are labelled):"
+            if decision.reason == "history"
+            else "Memories to answer from (current, supported for this message):"
+        )
+        lines = [heading]
+        for index, row in enumerate(decision.memories, start=1):
+            details = _memory_details(row)
+            lines.append(f"[{index}]" + (f" ({'; '.join(details)})" if details else ""))
+            lines.append(str(row.get("content") or ""))
+        sections.append("\n".join(lines))
+    return "\n\n".join(sections)

{hebbrix-2.7.0 → hebbrix-2.8.0}/hebbrix/client.py

@@ -93,7 +93,7 @@ class MemoryClient:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.7.0",
+            "User-Agent": "hebbrix-python/2.8.0",
         }
 
         if self.api_key:
@@ -302,8 +302,12 @@ class MemoryClient:
         group_by_source: bool = True,
         debug: bool = False,
         view: Optional[str] = None,
+        include_superseded: bool = False,
+        include_profile: bool = False,
     ) -> Dict[str, Any]:
-        """Search and return both results and the automatic ProofLoop context."""
+        """Search and return the response's rows, its abstention fields
+        (``answer_status``, ``abstain_recommended``: ``hebbrix.should_answer``
+        decides from them) and the automatic ProofLoop context."""
 
         return await self.search_resource.search_with_proof(
             query=query,
@@ -320,6 +324,8 @@ class MemoryClient:
             group_by_source=group_by_source,
             debug=debug,
             view=view,
+            include_superseded=include_superseded,
+            include_profile=include_profile,
         )
 
     async def reason(
@@ -334,6 +340,7 @@ class MemoryClient:
         facets: Optional[List[str]] = None,
         view: str = "compact",
         debug: bool = False,
+        deadline_ms: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Perform reasoning over memories.
@@ -349,6 +356,7 @@ class MemoryClient:
             facets: Optional typed decomposition facets
             view: ``"compact"`` (default) or ``"full"`` diagnostics
             debug: Return the full diagnostic response
+            deadline_ms: The response's latency budget, at most the server's
 
         Returns:
             Reasoning result with answer and sources
@@ -364,6 +372,7 @@ class MemoryClient:
             facets=facets,
             view=view,
             debug=debug,
+            deadline_ms=deadline_ms,
         )
 
     async def close(self):