memleaf 0.2.43__tar.gz → 0.2.45__tar.gz

{memleaf-0.2.43 → memleaf-0.2.45}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.45 — 2026-09-12
+
+- Repair the `b3-single-pass-v1` automatic extraction contract so model output is constrained by the same CREATE / UPDATE / NO_CHANGE / DEFERRED fields, evidence shapes, no-memory/defer reasons, target rules and lookup-completeness checks that Core validates. Pure ASCII decision-case differences are normalized locally; unknown decisions and missing semantic fields still fail closed.
+- Replace the generic second full-prompt retry with one B3-specific structural repair. The repair receives only the previous untrusted B3 object, the compact protocol and allowlisted structural diagnostics; Core rejects candidate count/order changes, evidence/target/scope/memory drift, or any edit outside the explicitly repairable protocol redundancy. Automatic extraction remains limited to at most two actual model requests and never fabricates a terminal disposition.
+- Separate credential/profile name (`provider`), wire protocol (`protocol`) and capability identity (`provider_family`). DeepSeek capabilities are resolved only from explicit configuration, exact legacy provider IDs, or exact official hostnames; custom aliases, model-name substrings and lookalike domains no longer grant provider-specific JSON/thinking behavior or override an explicit protocol. Unknown OpenAI-compatible services fail closed for single-pass capability.
+- Make DeepSeek single-pass primary and repair requests send explicit `thinking: {type: disabled}` and `response_format: {type: json_object}` from the resolved capability profile, with independently configurable bounded output ceilings. Finish-reason truncation is rejected before commit, repair output is never truncated to fit a budget, and transport success, parser rejection and commit acceptance remain separate metrics.
+- Refine thinking telemetry to distinguish requested, applied and observed state, preserve missing usage as unknown, and report observed reasoning when provider usage or response content proves it. The HTTP transport base no longer grants `single_pass_safe` by inheritance; B3 protocol compatibility and bounded one-request transport semantics are evaluated separately.
+- Validation for this release used the exact v0.2.44 source artifact at `c13c6dedacfdf6206fd8ebdaa04c4d84fdc0b919`: 88 focused tests passed, including temporary-Vault atomicity/idempotency/revision-conflict boundaries, provider request serialization, B3 repair fidelity, request-count limits and the advisory ten-second latency rule. No real provider call or production-session replay was used, so real-model first-pass success rate, repair success rate, reasoning reduction and latency improvement remain unmeasured.
+
+## 0.2.44 — 2026-09-12
+
+- Correct the extraction latency policy: ten seconds is an advisory performance target, not a cancellation or commit deadline. Remove the fixed six-second primary cap and eight-second shared window; single-pass HTTP requests now honor `llm.request_timeout`, including the one bounded format repair.
+- Accept valid, Core-checked results after the target and recover frozen background plans without expiring them by old wall-clock timestamps. Keep durable request counts, damaged-state handling, revision/ownership validation and normal transport errors intact.
+- Add structural per-turn extraction timing to synchronous results and background job result/error summaries. Track planning/commit time, slow attempts and failed attempts separately; a fast failure is not counted as successful target achievement. No prompt, response, credential or memory body is added to these metrics.
+- Keep tests local-only and leave the hosted build/smoke CI policy unchanged. Real-provider latency and quality acceptance remain separate; removing premature cancellation is not a measured ten-second performance claim.
+
 ## 0.2.43 — 2026-09-12
 
 - Keep regression tests, live-acceptance helpers, and implementation/release plans in local checkouts rather than the Git tree or source distribution.

{memleaf-0.2.43/src/memleaf.egg-info → memleaf-0.2.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.43
+Version: 0.2.45
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.43。**
+> **版本：0.2.45。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -85,6 +85,8 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+**10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
+
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
 
 - `CREATE`：没有相关现存记忆，创建一条原子、可独立理解的记忆；

{memleaf-0.2.43 → memleaf-0.2.45}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.43.**
+> **Version: 0.2.45.**
 > Automatic extraction now uses only the current turn's visible user input and final assistant reply. Raw tool output, attachments, web/file/terminal payloads and legacy tool-evidence bodies are not new source evidence; existing or retrieved memory remains comparison context rather than source authority. Background processing is persisted as a local job and can be checked through the read-only `process_status` MCP tool; failed work remains retryable and fail closed. The release also tightens source/date grounding, target reconciliation, duplicate/no-op handling and semantic review before writes. Markdown remains the sole source of truth with no SQLite runtime dependency. Acceptance covers deterministic regression suites and synthetic inputs; it does not claim real-mail or customer-business acceptance.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
@@ -64,6 +64,8 @@ Hermes uses a native MemoryProvider for lifecycle handling and obtains the Scope
 
 ## Memory admission and maintenance
 
+**Ten seconds is an extraction performance target, not a failure deadline.** HTTP requests honor `llm.request_timeout` (120 seconds by default). A valid, Core-checked response is not discarded just because processing exceeds ten seconds. Single-pass planning, bounded repair and per-turn commits remain; completion and latency are measured separately. See [extraction latency and timeouts](docs/extraction-latency.md).
+
 memleaf does not save every sentence. When a complete visible user + assistant turn is processed, the model first evaluates whether it has concrete future reuse value:
 
 - `CREATE`: no related active memory exists, so create one atomic, self-contained memory;

{memleaf-0.2.43 → memleaf-0.2.45}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.43。**
+> **版本：0.2.45。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -66,6 +66,8 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+**10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
+
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
 
 - `CREATE`：没有相关现存记忆，创建一条原子、可独立理解的记忆；

memleaf-0.2.45/docs/extraction-latency.md

@@ -0,0 +1,50 @@
+# 提炼耗时与请求超时
+
+## 性能目标与失败条件分开
+
+日常自动提炼以 10 秒内完成为性能目标，但到第 10 秒不会主动报失败，也不会丢弃已正常返回并通过 Core 校验的结果。超过目标说明本次处理偏慢，不说明记忆无效或没有需要保存的信息。
+
+v0.2.42 / v0.2.43 的固定 6 秒首请求、8 秒准备加模型窗口、10 秒提交前拒绝属于错误的目标实现，当前修正移除了这些时间闸门。修正本身不代表真实模型的 P50/P95 已达标。
+
+HTTP 请求使用已有配置：
+
+```yaml
+llm:
+  request_timeout: 120
+```
+
+这个参数仍按现有规则校验（1～240 秒，可用小数），并传到 HTTP transport。single-pass 不再静默把它缩短为 6 秒。第二次结构修复请求使用相同的配置，不再只分到原来 8 秒窗口的剩余时间。请求超时是 transport 的等待限制，不是整个后台任务的端到端完成保证；host/Python callback 仍由其宿主负责请求超时与取消。
+
+真正的请求超时、网络故障、无效模型输出、目标版本冲突、写入失败仍然是失败或未完成，不能伪装为 `NO_CHANGE`。相应 inbox、journal 和恢复锚点保留，是否提交仍由 Core 校验决定。
+
+## 保留的调用与提交约束
+
+普通 B3 自动提炼仍以一次结构化模型调用为正常路径，格式/结构修复最多一次。固定安全路由保留实际 outbound 请求计数和持久化预占，不增加隐藏 host-to-API fallback。并未恢复 Gate → Summary → Review 多阶段主路径。
+
+每轮仍先读取持久状态、规划、校验、提交，再处理下一轮；一轮超过目标不会占用下一轮的“时间许可”。compaction 仍不在普通提炼的关键路径上。
+
+旧 `extraction_request_budget.json` 中的 `started_at_epoch` 可以兼容读取，但不再作为请求或提交的过期时间。已消耗的 `requests` 不清零，损坏的计数账本也不会被当作空文件重建。FrozenTurn 的恢复不需要重新申请模型时间窗口；现有内容摘要、版本、所有权和写入校验保持不变。
+
+这不是一个自动重放所有历史失败任务的迁移。旧 inbox 不会被清空；需要通过正常处理/重试入口继续处理，不能删除正确性状态来强行重新获取请求额度。
+
+## 只记录结构化耗时
+
+处理结果新增 `extraction_metrics`，后台 `process_status` 的 result/error 和尝试汇总保留同样的数字字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `target_duration_ms` | 固定观测目标 10000 毫秒，不参与失败判断 |
+| `turn_count` | 本次测量的 turn 尝试数量 |
+| `failed_turn_count` | 抛出处理异常的 turn 尝试数量 |
+| `over_target_turn_count` | 耗时超过目标的 turn 尝试数量，可能成功也可能失败 |
+| `successful_within_target_count` | 无处理异常且在目标内结算的尝试数量 |
+| `total_duration_ms` | 被测 turn 尝试的耗时之和 |
+| `max_turn_duration_ms` | 最慢一次 turn 尝试耗时 |
+| `planning_duration_ms` | 读取状态、准备上下文、模型调用和本地计划校验耗时 |
+| `commit_duration_ms` | 从进入提交阶段到提交和预算清理返回的耗时 |
+
+每轮计时从选中该 turn 后、读取其处理状态前开始。它不包括排队、worker 启动及 `process()` 开头的整批 inbox claim 扫描；不能把该指标冒充用户可见端到端耗时。跨 worker 重启会产生新的尝试，旧进程的 wall-clock 起点不再限制新进程执行。
+
+“无处理异常”包括合法 `NO_CHANGE` 和正常返回的部分处理；语义完整性仍由既有 `coverage_status`、deferred 数量、`memories_written` 和任务状态判断。因此耗时统计不替代提炼质量验收。快速失败不计入 `successful_within_target_count`。
+
+`model_metrics` 继续分别提供模型请求耗时、调用/修复次数和输入输出长度等信息。以上结构化统计不新增正文、prompt、response 或凭证存储。

{memleaf-0.2.43 → memleaf-0.2.45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memleaf"
-version = "0.2.43"
+version = "0.2.45"
 description = "A local-first Markdown memory core for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memleaf-0.2.43 → memleaf-0.2.45}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.43"
+__version__ = "0.2.45"
 
 from .config import DEFAULT_CONFIG, default_config, load_config, save_config
 from .frontmatter import FrontmatterError, dump_frontmatter, dump_yaml, load_yaml, parse_frontmatter

{memleaf-0.2.43 → memleaf-0.2.45}/src/memleaf/cli.py

@@ -22,6 +22,7 @@ from .adapters.base import (
 from .adapters.hermes import HermesAdapter
 from .credentials import credential_text
 from .config import load_config
+from .model_capabilities import resolve_provider_capabilities
 from .model_discovery import ModelCandidate, discover_models, manual_candidate, write_model_config
 from .vault import Vault
 
@@ -531,6 +532,11 @@ def _existing_memleaf_route(path: Path) -> ModelCandidate | None:
     if key is None:
         return None
     try:
+        capabilities = resolve_provider_capabilities(
+            provider=llm.get("provider"),
+            provider_family=llm.get("provider_family"),
+            base_url=llm.get("base_url"),
+        )
         return ModelCandidate(
             source="memleaf",
             provider=str(llm.get("provider", "")),
@@ -540,6 +546,8 @@ def _existing_memleaf_route(path: Path) -> ModelCandidate | None:
             api_key=key,
             context_window=int(llm.get("context_window", 200000)),
             source_detail="existing memleaf route",
+            provider_family=capabilities.provider_family,
+            provider_family_source=capabilities.source,
         )
     except (TypeError, ValueError):
         return None
@@ -547,13 +555,17 @@ def _existing_memleaf_route(path: Path) -> ModelCandidate | None:
 
 def _prompt_for_model() -> ModelCandidate:
     print("memleaf: no complete callable chat model was found; configure one for processing.", file=sys.stderr)
-    provider = input("Provider (openai/claude/gemini): ").strip()
+    provider = input("Provider / credential profile name: ").strip()
+    provider_family = input(
+        "Provider family (openai/deepseek/anthropic/gemini/generic, blank=auto): "
+    ).strip()
     protocol = input("Protocol (openai/claude/gemini): ").strip()
     base_url = input("Base URL: ").strip()
     model = input("Model: ").strip()
     api_key = getpass.getpass("API key (input hidden): ")
     return manual_candidate(
         provider=provider,
+        provider_family=provider_family,
         protocol=protocol,
         base_url=base_url,
         model=model,

{memleaf-0.2.43 → memleaf-0.2.45}/src/memleaf/config.py

@@ -9,6 +9,9 @@ from typing import Any, Mapping
 
 from .frontmatter import FrontmatterError, dump_yaml, load_yaml
 from .locking import atomic_write_text
+from .model_capabilities import (
+    legacy_protocol_for_provider, normalize_protocol, normalize_provider_family,
+)
 from .native_index import NativeConfigError, validate_native_sources
 from .scope_state import ScopeError, validate_scope_registry
 
@@ -19,6 +22,10 @@ MAX_REQUEST_TIMEOUT = 240
 DEFAULT_MODEL_CONCURRENCY = 3
 MIN_MODEL_CONCURRENCY = 1
 MAX_MODEL_CONCURRENCY = 8
+DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS = 8192
+DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS = 8192
+MIN_SINGLE_PASS_MAX_TOKENS = 2048
+MAX_SINGLE_PASS_MAX_TOKENS = 32768
 THINKING_PURPOSES = ("gate", "summarize", "compact", "single_pass")
 THINKING_MODES = frozenset({"default", "disabled", "low", "high", "max"})
 DEFAULT_THINKING = {purpose: "low" for purpose in THINKING_PURPOSES}
@@ -40,6 +47,16 @@ def _normalize_request_timeout(value: Any) -> int | float:
     return int(parsed) if parsed.is_integer() else parsed
 
 
+def _normalize_single_pass_token_limit(value: Any, *, field: str, default: int) -> int:
+    if value is None or value == "":
+        return default
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"invalid memleaf llm.{field}")
+    if not MIN_SINGLE_PASS_MAX_TOKENS <= value <= MAX_SINGLE_PASS_MAX_TOKENS:
+        raise ValueError(f"invalid memleaf llm.{field}")
+    return value
+
+
 def _normalize_model_concurrency(value: Any) -> int:
     if isinstance(value, bool) or not isinstance(value, int):
         raise ValueError("invalid memleaf process.model_concurrency")
@@ -89,6 +106,7 @@ DEFAULT_CONFIG: dict[str, Any] = {
     "llm": {
         "mode": "auto",
         "provider": "",
+        "provider_family": "",
         "protocol": "openai",
         "base_url": "",
         "api_key": "",
@@ -96,6 +114,8 @@ DEFAULT_CONFIG: dict[str, Any] = {
         "model": "",
         "context_window": 200000,
         "request_timeout": DEFAULT_REQUEST_TIMEOUT,
+        "single_pass_primary_max_tokens": DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS,
+        "single_pass_repair_max_tokens": DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS,
         "diagnostic_logging": False,
         "thinking": dict(DEFAULT_THINKING),
     },
@@ -148,6 +168,19 @@ def _normalize_legacy_config(value: Mapping[str, Any]) -> dict[str, Any]:
             # the current default restore normal bounded evidence capture.
             current["tool_evidence_mode"] = "off"
         normalized["capture"] = current
+    llm = normalized.get("llm")
+    if llm is not None and not isinstance(llm, Mapping):
+        raise ValueError("invalid memleaf llm settings")
+    if isinstance(llm, Mapping):
+        current_llm = dict(llm)
+        # Old configs often omitted protocol and relied on the provider name.
+        # Preserve only exact built-in identifiers; custom aliases never
+        # override an explicitly configured protocol.
+        if not isinstance(current_llm.get("protocol"), str) or not current_llm.get("protocol", "").strip():
+            legacy_protocol = legacy_protocol_for_provider(current_llm.get("provider"))
+            if legacy_protocol is not None:
+                current_llm["protocol"] = legacy_protocol
+        normalized["llm"] = current_llm
     return normalized
 
 
@@ -210,7 +243,17 @@ def load_config(path: Path | str, *, vault: Path | str | None = None) -> dict[st
     if not isinstance(llm, Mapping):
         raise ValueError("invalid memleaf llm settings")
     llm = dict(llm)
+    llm["provider_family"] = normalize_provider_family(llm.get("provider_family"))
+    llm["protocol"] = normalize_protocol(llm.get("protocol"), provider=llm.get("provider"))
     llm["request_timeout"] = _normalize_request_timeout(llm.get("request_timeout", DEFAULT_REQUEST_TIMEOUT))
+    llm["single_pass_primary_max_tokens"] = _normalize_single_pass_token_limit(
+        llm.get("single_pass_primary_max_tokens"),
+        field="single_pass_primary_max_tokens", default=DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS,
+    )
+    llm["single_pass_repair_max_tokens"] = _normalize_single_pass_token_limit(
+        llm.get("single_pass_repair_max_tokens"),
+        field="single_pass_repair_max_tokens", default=DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS,
+    )
     llm["thinking"] = _normalize_thinking_settings(llm.get("thinking"))
     if type(llm.get("diagnostic_logging", False)) is not bool:
         raise ValueError("invalid memleaf llm.diagnostic_logging")
@@ -252,9 +295,21 @@ def save_config(path: Path | str, config: Mapping[str, Any]) -> None:
     if not isinstance(llm, Mapping):
         raise ValueError("invalid memleaf llm settings")
     normalized_llm = dict(llm)
+    normalized_llm["provider_family"] = normalize_provider_family(normalized_llm.get("provider_family"))
+    normalized_llm["protocol"] = normalize_protocol(
+        normalized_llm.get("protocol"), provider=normalized_llm.get("provider")
+    )
     normalized_llm["request_timeout"] = _normalize_request_timeout(
         normalized_llm.get("request_timeout", DEFAULT_REQUEST_TIMEOUT)
     )
+    normalized_llm["single_pass_primary_max_tokens"] = _normalize_single_pass_token_limit(
+        normalized_llm.get("single_pass_primary_max_tokens"),
+        field="single_pass_primary_max_tokens", default=DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS,
+    )
+    normalized_llm["single_pass_repair_max_tokens"] = _normalize_single_pass_token_limit(
+        normalized_llm.get("single_pass_repair_max_tokens"),
+        field="single_pass_repair_max_tokens", default=DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS,
+    )
     normalized_llm["thinking"] = _normalize_thinking_settings(normalized_llm.get("thinking"))
     diagnostic_logging = normalized_llm.get("diagnostic_logging", False)
     if type(diagnostic_logging) is not bool:

memleaf-0.2.45/src/memleaf/extraction_budget.py

@@ -0,0 +1,210 @@
+"""Outbound-request accounting and advisory extraction latency metrics.
+
+Ten seconds is a performance target, not permission to cancel useful work or
+discard a valid memory. The transport owns the configured request timeout;
+this module only limits request count and observes complete-turn latency.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, Iterable, Mapping
+
+from .llm import ModelError
+
+
+MAX_MODEL_REQUESTS = 2
+TARGET_TOTAL_SECONDS = 10.0
+
+
+class SinglePassBudgetBackend:
+    """Limit one logical B3 turn to two actual provider requests.
+
+    ``single_pass_safe`` routes map one complete() call to one request, without
+    hidden host-to-API fallback. The optional durable reservation preserves
+    consumed attempts across worker restarts. Neither the first request nor
+    its repair overrides the transport's configured ``llm.request_timeout``.
+    """
+
+    def __init__(
+        self,
+        backend: Any,
+        *,
+        reserve_request: Callable[[], int | None] | None = None,
+    ):
+        if not hasattr(backend, "complete"):
+            raise TypeError("single-pass backend must expose complete()")
+        if reserve_request is not None and not callable(reserve_request):
+            raise TypeError("reserve_request must be callable")
+        self._backend = backend
+        self._requests = 0
+        self._reserve_request = reserve_request
+
+    @property
+    def provider(self) -> str:
+        return str(getattr(self._backend, "provider", "unknown"))
+
+    @property
+    def model(self) -> str:
+        return str(getattr(self._backend, "model", "unknown"))
+
+    @property
+    def single_pass_safe(self) -> bool:
+        """Preserve the underlying adapter/route request-boundary guarantee."""
+
+        return getattr(self._backend, "single_pass_safe", False) is True
+
+    @property
+    def single_pass_protocol(self) -> bool:
+        """Preserve protocol identity while this wrapper enforces request count."""
+
+        return getattr(self._backend, "single_pass_protocol", False) is True
+
+    @property
+    def parallel_safe(self) -> bool:
+        return getattr(self._backend, "parallel_safe", False) is True
+
+    @property
+    def structured_batch_safe(self) -> bool:
+        return getattr(self._backend, "structured_batch_safe", False) is True
+
+    @property
+    def request_count(self) -> int:
+        return self._requests
+
+    def _request_ordinal(self, *, purpose: str) -> int:
+        if self._requests >= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        if self._reserve_request is None:
+            return self._requests + 1
+        try:
+            ordinal = self._reserve_request()
+        except Exception as error:
+            raise ModelError(
+                "single-pass extraction request budget cannot be reserved",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            ) from error
+        if type(ordinal) is not int or not 1 <= ordinal <= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        return ordinal
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        system: str = "",
+        purpose: str = "",
+        temperature: float = 0.0,
+    ) -> str:
+        self._request_ordinal(purpose=purpose)
+        # Count only after durable reservation succeeds. A kill from this point
+        # onward still consumes that attempt, without imposing a wall deadline.
+        self._requests += 1
+        return self._backend.complete(
+            prompt,
+            system=system,
+            purpose=purpose,
+            temperature=temperature,
+        )
+
+    def consume_call_metrics(self) -> dict[str, Any]:
+        consume = getattr(self._backend, "consume_call_metrics", None)
+        if not callable(consume):
+            return {}
+        try:
+            value = consume()
+        except Exception:
+            return {}
+        return dict(value) if isinstance(value, Mapping) else {}
+
+
+class ExtractionTiming:
+    """Observe one processing attempt; never authorize or reject a write.
+
+    This monotonic timer includes local planning/context, model work, validation
+    and commit. A worker restart begins a new measured attempt; persisted wall
+    timestamps from older releases are not latency-based write restrictions.
+    """
+
+    def __init__(self, *, clock: Any = None):
+        self._clock = time.monotonic if clock is None else clock
+        self._started = self._clock()
+        self._commit_started: float | None = None
+
+    def begin_commit(self) -> None:
+        self._commit_started = self._clock()
+
+    def finish(self, *, failed: bool = False) -> dict[str, int]:
+        ended = self._clock()
+        seconds = max(0.0, ended - self._started)
+        commit_started = self._commit_started
+        planning_end = ended if commit_started is None else commit_started
+        return {
+            "target_duration_ms": int(TARGET_TOTAL_SECONDS * 1000),
+            "turn_count": 1,
+            "failed_turn_count": int(failed),
+            "over_target_turn_count": int(seconds > TARGET_TOTAL_SECONDS),
+            "successful_within_target_count": int(not failed and seconds <= TARGET_TOTAL_SECONDS),
+            "commit_accepted_count": int(not failed and commit_started is not None),
+            "total_duration_ms": int(seconds * 1000),
+            "max_turn_duration_ms": int(seconds * 1000),
+            "planning_duration_ms": int(max(0.0, planning_end - self._started) * 1000),
+            "commit_duration_ms": int(max(0.0, ended - planning_end) * 1000),
+        }
+
+
+def aggregate_extraction_metrics(values: Iterable[Mapping[str, Any]]) -> dict[str, int]:
+    """Sum allowlisted numeric metrics; never copy arbitrary content to status."""
+
+    summed = (
+        "turn_count", "failed_turn_count", "over_target_turn_count",
+        "successful_within_target_count", "commit_accepted_count", "total_duration_ms",
+        "planning_duration_ms", "commit_duration_ms",
+    )
+    result = {key: 0 for key in summed}
+    result["target_duration_ms"] = int(TARGET_TOTAL_SECONDS * 1000)
+    result["max_turn_duration_ms"] = 0
+    for value in values:
+        if not isinstance(value, Mapping):
+            continue
+        for key in (*summed, "max_turn_duration_ms"):
+            item = value.get(key)
+            if type(item) is not int or item < 0:
+                continue
+            if key == "max_turn_duration_ms":
+                result[key] = max(result[key], item)
+            else:
+                result[key] += item
+    return result
+
+
+def budget_single_pass_backend(
+    backend: Any,
+    *,
+    reserve_request: Callable[[], int | None] | None = None,
+) -> SinglePassBudgetBackend:
+    if isinstance(backend, SinglePassBudgetBackend):
+        return backend
+    return SinglePassBudgetBackend(
+        backend,
+        reserve_request=reserve_request,
+    )
+
+
+__all__ = [
+    "MAX_MODEL_REQUESTS",
+    "TARGET_TOTAL_SECONDS",
+    "ExtractionTiming",
+    "aggregate_extraction_metrics",
+    "SinglePassBudgetBackend",
+    "budget_single_pass_backend",
+]

{memleaf-0.2.43 → memleaf-0.2.45}/src/memleaf/extraction_capability.py

@@ -1,10 +1,9 @@
 """Capability checks for unified automatic extraction.
 
-Protocol compatibility and hard latency safety are intentionally separate.
-A backend may understand the B3 single-pass contract without being able to
-honor transport-level cancellation/deadlines. Automatic extraction can use
-one semantic protocol in both cases, while Processor applies the strict
-8/10-second budget only to ``single_pass_safe`` transports.
+Protocol compatibility and transport request accounting are separate.
+A backend may understand the B3 contract without exposing a bounded transport.
+``single_pass_safe`` identifies routes suitable for outbound-request counting;
+HTTP requests use the configured timeout, not the advisory ten-second target.
 """
 from __future__ import annotations
 
@@ -33,25 +32,25 @@ def _direct_protocol_capable(backend: Any) -> bool:
 
     if backend is None:
         return False
-    if getattr(backend, "single_pass_safe", False) is True:
-        return True
-    declared = getattr(backend, "single_pass_protocol", None)
-    if isinstance(declared, bool):
-        return declared
+    # Raw Python callbacks are adapted by ModelExecutor into CallableBackend.
+    # Preserve their established prompt-level B3 compatibility without
+    # claiming any transport boundary inside caller-owned code.  An explicit
+    # callback override can still opt out.
     if isinstance(backend, CallableBackend):
         override = _callable_protocol_override(backend)
         if override is not None:
             return override
-        # Raw Python callbacks are adapted by ModelExecutor into
-        # CallableBackend. They can consume memleaf's B3 prompt, but are not
-        # strict-deadline safe because caller-owned code may ignore
-        # timeout/cancellation entirely.
         return True
+    # Protocol support is independent of request-boundary safety.  A backend
+    # must not gain B3 merely because complete() happens to be bounded.
+    declared = getattr(backend, "single_pass_protocol", None)
+    if isinstance(declared, bool):
+        return declared
     return False
 
 
 def supports_single_pass_protocol(backend: Any) -> bool:
-    """Return B3 protocol capability without claiming strict transport SLA."""
+    """Return B3 protocol capability without claiming transport guarantees."""
 
     if _direct_protocol_capable(backend):
         return True