memleaf 0.2.41__tar.gz → 0.2.43__tar.gz

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

@@ -2,6 +2,21 @@
 
 All notable changes to memleaf are documented here.
 
+## 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.
+- Narrow hosted CI to package build and installed-command smoke checks while retaining the existing release metadata checks and GitHub/PyPI publication workflow.
+
+## 0.2.42 — 2026-09-12
+
+- Rework ordinary automatic extraction around the unified `b3-single-pass-v1` planner. The current visible user/assistant turn is the only new-fact evidence; existing local/native memories remain comparison context. One structured model stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, with deterministic Core validation and at most one bounded format/structure repair.
+- Make the latency-critical `single_pass` stage non-thinking by default and use bounded structured output for supported OpenAI-compatible routes. Fixed safe API routes enforce a six-second primary request cap, an eight-second preparation-plus-model window, a ten-second total turn deadline, and rejection of late results before commit; no unmeasured P50/P95 claim is made.
+- Persist background extraction request/time budgets by process-job and turn identity so worker restarts cannot regain consumed attempts or wall time. Damaged budget/job state, invalid ownership/order, and wall-clock rollback fail closed instead of reopening a fresh extraction budget.
+- Commit automatic processing one complete turn at a time and re-read durable Markdown/journal state before planning the next turn. Frozen-turn recovery preserves already committed work without replaying model calls/history, while one process invocation drains at most four claimed turns and exposes the remaining backlog explicitly.
+- Move compaction/maintenance out of the `process()` / `remember()` extraction critical path, keep explicit no-write instructions as deterministic zero-model-call settlements, and retain structural-only model telemetry without prompt/response bodies or credentials.
+- Separate B3 protocol compatibility from strict transport deadline safety. Host/Python callbacks can use the same B3 semantic protocol without falsely claiming hard cancellation; mixed auto routes remain fail-closed, `single_pass` forbids hidden host-to-API fallback, and explicit `remember()` keeps its existing bounded validator retry semantics.
+- Preserve the product architecture: Markdown under `knowledge/` remains the active source of truth, `history/` remains historical state, permanent memory stays globally shared across agents using the same Vault, and no database, Redis, vector service, resident daemon, or local-model dependency is introduced. The release candidate passed Linux Python 3.11/3.12/3.13, Windows Python 3.11/3.12/3.13, macOS Python 3.11/3.13, native Codex Windows/macOS, wheel/sdist, installed-entry-point, and full unittest CI; real-model quality/latency acceptance remains a separate user-run step.
+
 ## 0.2.41 — 2026-09-11
 
 - Promote the B3 single-pass automatic memory planner for explicitly `single_pass_safe` API backends. Core prepares bounded local retrieval/context once, one semantic planner stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, deterministic validation remains authoritative, and model-output repair is bounded to at most one retry (`max_attempts=2`). Host/custom/host-backed providers keep the proven P3 fallback, while explicit `remember` retains its existing single-summary path.

{memleaf-0.2.41 → memleaf-0.2.43}/MANIFEST.in

@@ -4,9 +4,8 @@ include install.sh
 include install.ps1
 include README.md
 include README.en.md
-include RELEASE_CHECKLIST.md
-include IMPLEMENTATION_PLAN.md
-recursive-include tests *.py
 recursive-include examples *.md *.ndjson *.py
+recursive-exclude examples *_acceptance.py
+prune tests
 
 include docs/*.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.41
+Version: 0.2.43
 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.41。**
+> **版本：0.2.43。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -451,17 +451,9 @@ history:
 - 选择 API/云端模型后，模型处理输入会离开本机并发送给该提供方；
 - `context()` 或无宿主绑定的客户端只能获得单页边界，不能宣称具备跨轮硬预算。
 
-## 开发与验证
+## 开发与构建
 
-要求 Python 3.11+。本地运行测试：
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
-
-GitHub Actions 覆盖 Linux 与 Windows 的 Python 3.11、3.12、3.13 测试，并验证 wheel/source distribution 构建、源码包测试和 Windows PowerShell 安装器语法。构建发行包需要 `build`：
+要求 Python 3.11+。GitHub Actions 在 Python 3.12 上构建 wheel 和 source distribution，并对安装后的包、命令入口和版本信息做冒烟检查。构建发行包需要 `build`：
 
 ```bash
 python -m pip install build

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

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.41.**
+> **Version: 0.2.43.**
 > 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.
 
@@ -434,17 +434,9 @@ Directories are normally created with mode `0700`, and files are stored as plain
 - If an API or cloud model is selected, model-processing input leaves the machine and is sent to that provider.
 - `context()` and clients without a host-bound retrieval turn only have per-page limits; they cannot claim cross-turn hard budgets.
 
-## Development and verification
+## Development and builds
 
-Python 3.11+ is required. Run locally:
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
-
-GitHub Actions covers Python 3.11, 3.12, and 3.13 on Linux and Windows, plus wheel/source-distribution builds, source-archive tests, and PowerShell installer syntax validation. Build packages with:
+Python 3.11+ is required. GitHub Actions builds the wheel and source distribution on Python 3.12, then smoke-checks the installed package, CLI entry points, and version commands. Build packages with:
 
 ```bash
 python -m pip install build

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

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.41。**
+> **版本：0.2.43。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -432,17 +432,9 @@ history:
 - 选择 API/云端模型后，模型处理输入会离开本机并发送给该提供方；
 - `context()` 或无宿主绑定的客户端只能获得单页边界，不能宣称具备跨轮硬预算。
 
-## 开发与验证
+## 开发与构建
 
-要求 Python 3.11+。本地运行测试：
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
-
-GitHub Actions 覆盖 Linux 与 Windows 的 Python 3.11、3.12、3.13 测试，并验证 wheel/source distribution 构建、源码包测试和 Windows PowerShell 安装器语法。构建发行包需要 `build`：
+要求 Python 3.11+。GitHub Actions 在 Python 3.12 上构建 wheel 和 source distribution，并对安装后的包、命令入口和版本信息做冒烟检查。构建发行包需要 `build`：
 
 ```bash
 python -m pip install build

{memleaf-0.2.41 → memleaf-0.2.43}/docs/general-processing.md

@@ -122,11 +122,15 @@ the preview. There is deliberately no apply-preview command.
 
 ## Verification boundaries
 
+The regression suite and acceptance helpers referenced here are maintained
+locally and are not included in this repository or its source distribution.
+Remote CI validates package construction and installed command entry points only.
+
 Deterministic backends test schema and filesystem behavior, not hosted-model
-accuracy. tests/semantic_fixtures.py adapts prescribed old Gate judgments to the
-quote protocol for update/history/maintenance tests. It does not run in product
-code and is not proof those judgments are semantically sound. New adversarial
-protocol tests choose their quotations explicitly. No model score or absolute
+accuracy. The local-only `tests/semantic_fixtures.py` adapts prescribed old Gate
+judgments to the quote protocol for update/history/maintenance tests. It does
+not run in product code and is not proof those judgments are semantically sound.
+New adversarial protocol tests choose their quotations explicitly. No model score or absolute
 "all languages/all scenarios" accuracy claim is made.
 
 Before release, separately inspect live Model Route behavior on held-out real
@@ -142,20 +146,23 @@ that acceptance.
 Windows processing-owner liveness is queried through a process handle with
 SYNCHRONIZE access, never by sending a signal. Shared-Vault writes use a
 native byte-range lock between processes, not only a Python thread mutex.
-Native child-process tests run on Linux, macOS and Windows.
-
-The full Python suite runs on all three OS families. Only the `install.sh`
-shell-harness class is POSIX-only; Windows retains installation, upgrade,
-PowerShell syntax, host lifecycle and native Codex acceptance. Test launchers
-use native `.cmd` wrappers on Windows. Byte-preservation assertions compare
-actual before/after bytes, including CRLF. POSIX mode-bit checks are conditional:
-Windows file privacy follows the Vault directory's inherited ACLs, and Unix
-`0600` must not be interpreted as proof of a Windows owner-only DACL.
-
-Real-model acceptance requires an explicit model route in repository Actions:
-secret `MEMLEAF_LIVE_MODEL_TOKEN` and variables `MEMLEAF_LIVE_BASE_URL` and
-`MEMLEAF_LIVE_MODEL`. Missing configuration is a blocked acceptance result,
-not a passing semantic test. Never publish based only on deterministic mocks.
+The local-only Python suite is intended to run on all three OS families; remote
+CI does not exercise it. Native child-process tests cover Linux, macOS and
+Windows when run locally.
+
+Only the `install.sh` shell-harness class is POSIX-only; local Windows checks
+cover installation, upgrade, PowerShell syntax, host lifecycle and native Codex
+acceptance. Test launchers use native `.cmd` wrappers on Windows.
+Byte-preservation assertions compare actual before/after bytes, including CRLF.
+POSIX mode-bit checks are conditional: Windows file privacy follows the Vault
+directory's inherited ACLs, and Unix `0600` must not be interpreted as proof of a
+Windows owner-only DACL.
+
+Real-model acceptance requires an explicitly configured model route using
+`MEMLEAF_LIVE_MODEL_TOKEN`, `MEMLEAF_LIVE_BASE_URL`, and `MEMLEAF_LIVE_MODEL`.
+Live acceptance tooling is maintained locally and is not run by remote CI.
+Missing configuration is a blocked acceptance result, not a passing semantic
+test. Never publish based only on deterministic mocks.
 
 ## Capture policy
 

{memleaf-0.2.41 → memleaf-0.2.43}/docs/processing-quality-acceptance.md

@@ -2,6 +2,11 @@
 
 This document defines acceptance for automatic memory extraction without treating one validation layer as proof of another.
 
+The deterministic suite and acceptance helpers described below are maintained
+locally and are not committed or shipped. Remote CI currently validates package
+construction and installed command entry points only; the layers below are not
+automatically exercised by that workflow.
+
 ## Invariants
 
 - Markdown under `knowledge/` remains the active-memory source of truth; `history/` remains historical state.
@@ -45,9 +50,12 @@ Required checks include:
 
 Passing this layer proves only the deterministic contracts under test.
 
-### 2. Cross-platform CI and MCP/background-runtime verification
+### 2. Cross-platform local regression and MCP/background-runtime verification
 
-Run the repository's supported OS matrix and the process-job/MCP tests. Verify that detached worker status exposes the bounded metrics, reruns aggregate metrics safely, and no model call is made while the Vault write lock is held.
+Run the maintained local-only test suite on supported OSes and the
+process-job/MCP tests. Verify that detached worker status exposes the bounded
+metrics, reruns aggregate metrics safely, and no model call is made while the
+Vault write lock is held.
 
 Passing this layer proves the tested runtime paths and platforms. It does not prove that a real model will always extract every business fact.
 

memleaf-0.2.43/examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+`basic_usage.py` runs entirely offline. Without `--vault` it creates a
+temporary vault; pass a directory explicitly when you want to inspect the
+generated Markdown after the process exits.
+
+The example shows a lightweight `context()` directory followed by an explicit
+`read_page()` call for the selected entry. Directory results contain no body;
+long bodies can be read in subsequent pages using `next_offset` and `version`.
+
+The `mcp_stdio.ndjson` file contains one legacy initialization request and one
+modern discovery request. Pipe it to the stdio adapter with an explicit vault:
+
+```sh
+python -m memleaf.mcp_server --vault <your-vault> < examples/mcp_stdio.ndjson
+```
+
+The NDJSON file is request-only and intentionally contains no tool call,
+network endpoint, local path, or secret.

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

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.41"
+__version__ = "0.2.43"
 
 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.41 → memleaf-0.2.43}/src/memleaf/config.py

@@ -19,9 +19,13 @@ MAX_REQUEST_TIMEOUT = 240
 DEFAULT_MODEL_CONCURRENCY = 3
 MIN_MODEL_CONCURRENCY = 1
 MAX_MODEL_CONCURRENCY = 8
-THINKING_PURPOSES = ("gate", "summarize", "compact")
+THINKING_PURPOSES = ("gate", "summarize", "compact", "single_pass")
 THINKING_MODES = frozenset({"default", "disabled", "low", "high", "max"})
 DEFAULT_THINKING = {purpose: "low" for purpose in THINKING_PURPOSES}
+# Unified extraction is latency-sensitive and keeps deterministic validation in
+# Core.  Make the single-pass path non-thinking by default without changing
+# the established policy for maintenance/legacy stages.
+DEFAULT_THINKING["single_pass"] = "disabled"
 
 
 def _normalize_request_timeout(value: Any) -> int | float:

memleaf-0.2.43/src/memleaf/extraction_budget.py

@@ -0,0 +1,280 @@
+"""Latency and outbound-request budget for unified memory extraction.
+
+The budget is deliberately attached to one logical single-pass turn instead
+of to an HTTP adapter.  That keeps the product invariants (at most two actual
+model requests and a bounded end-to-end turn) independent from provider-
+specific prompt/transport details.
+"""
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from typing import Any, Mapping
+
+from .llm import ModelError
+
+
+MAX_MODEL_REQUESTS = 2
+TARGET_TOTAL_SECONDS = 10.0
+MODEL_TIME_BUDGET_SECONDS = 8.0
+PRIMARY_REQUEST_MAX_SECONDS = 6.0
+
+
+class SinglePassBudgetBackend:
+    """Wrap one safe backend with the extraction request/time budget.
+
+    ``single_pass_safe`` routes are already constrained so one ``complete()``
+    maps to one provider request (no host->API fallback).  The wrapper
+    therefore makes the two-call limit a true outbound-request limit for the
+    production B3 route, not merely a parser-attempt count.
+
+    ``deadline`` is absolute in the supplied monotonic clock.  Supplying it is
+    what lets preparation time consume the same turn budget instead of
+    starting a fresh eight-second clock only when the HTTP call begins.
+
+    ``reserve_request`` optionally persists the request ordinal before the
+    outbound call.  Background workers use it so a process restart cannot
+    reopen attempts already consumed by the same durable work item.
+    """
+
+    single_pass_safe = True
+
+    def __init__(
+        self,
+        backend: Any,
+        *,
+        clock: Any = time.monotonic,
+        deadline: float | None = None,
+        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._clock = clock
+        self._started = float(clock())
+        self._deadline = (
+            self._started + MODEL_TIME_BUDGET_SECONDS
+            if deadline is None
+            else float(deadline)
+        )
+        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 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 _remaining(self) -> float:
+        return self._deadline - float(self._clock())
+
+    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:
+        remaining = self._remaining()
+        if remaining <= 0:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        ordinal = self._request_ordinal(purpose=purpose)
+        cap = min(
+            PRIMARY_REQUEST_MAX_SECONDS if ordinal == 1 else remaining,
+            remaining,
+        )
+        if cap <= 0:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        # Count locally only after the durable reservation succeeded. A kill
+        # after this point still leaves the persistent ordinal consumed.
+        self._requests += 1
+
+        set_timeout = getattr(self._backend, "set_call_timeout", None)
+        clear_timeout = getattr(self._backend, "clear_call_timeout", None)
+        if callable(set_timeout):
+            set_timeout(cap)
+        try:
+            value = self._backend.complete(
+                prompt,
+                system=system,
+                purpose=purpose,
+                temperature=temperature,
+            )
+        finally:
+            if callable(clear_timeout):
+                try:
+                    clear_timeout()
+                except Exception:
+                    pass
+
+        # A callback/custom transport may ignore the timeout hook. Such a late
+        # result must never become writable merely because it eventually returned.
+        if self._remaining() < 0:
+            raise ModelError(
+                "single-pass extraction result arrived after deadline",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        return value
+
+    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 ExtractionWorkBudget:
+    """One monotonic budget beginning before preparation for a visible turn.
+
+    The first eight seconds are available to preparation plus model work. The
+    remaining two seconds are reserved for deterministic validation/commit.
+    If the ten-second total deadline has already elapsed, the turn is not
+    allowed to enter the mutation boundary.
+
+    ``elapsed_seconds`` restores wall time already consumed by the same durable
+    background work item before a worker restart. The persisted ledger uses a
+    wall clock only to derive that cross-process elapsed interval; after this
+    object is constructed, every new deadline check uses the supplied monotonic
+    clock in the current process.
+    """
+
+    def __init__(
+        self,
+        *,
+        clock: Any = time.monotonic,
+        elapsed_seconds: float = 0.0,
+    ):
+        if (
+            isinstance(elapsed_seconds, bool)
+            or not isinstance(elapsed_seconds, (int, float))
+            or not math.isfinite(float(elapsed_seconds))
+            or float(elapsed_seconds) < 0
+        ):
+            raise ValueError("elapsed_seconds must be a finite non-negative number")
+        self._clock = clock
+        current = float(clock())
+        elapsed = float(elapsed_seconds)
+        self._started = current - elapsed
+        self._model_deadline = current + (MODEL_TIME_BUDGET_SECONDS - elapsed)
+        self._total_deadline = current + (TARGET_TOTAL_SECONDS - elapsed)
+
+    @property
+    def started(self) -> float:
+        return self._started
+
+    @property
+    def model_deadline(self) -> float:
+        return self._model_deadline
+
+    @property
+    def total_deadline(self) -> float:
+        return self._total_deadline
+
+    def remaining_total(self) -> float:
+        return self._total_deadline - float(self._clock())
+
+    def wrap_backend(
+        self,
+        backend: Any,
+        *,
+        reserve_request: Callable[[], int | None] | None = None,
+    ) -> SinglePassBudgetBackend:
+        return budget_single_pass_backend(
+            backend,
+            clock=self._clock,
+            deadline=self._model_deadline,
+            reserve_request=reserve_request,
+        )
+
+    def ensure_before_commit(self) -> None:
+        if self.remaining_total() <= 0:
+            raise ModelError(
+                "single-pass extraction exceeded total deadline before commit",
+                code="model_timeout",
+                stage="single_pass",
+            )
+
+
+def budget_single_pass_backend(
+    backend: Any,
+    *,
+    clock: Any = time.monotonic,
+    deadline: float | None = None,
+    reserve_request: Callable[[], int | None] | None = None,
+) -> SinglePassBudgetBackend:
+    if isinstance(backend, SinglePassBudgetBackend):
+        return backend
+    return SinglePassBudgetBackend(
+        backend,
+        clock=clock,
+        deadline=deadline,
+        reserve_request=reserve_request,
+    )
+
+
+__all__ = [
+    "MAX_MODEL_REQUESTS",
+    "MODEL_TIME_BUDGET_SECONDS",
+    "PRIMARY_REQUEST_MAX_SECONDS",
+    "TARGET_TOTAL_SECONDS",
+    "ExtractionWorkBudget",
+    "SinglePassBudgetBackend",
+    "budget_single_pass_backend",
+]