memleaf 0.2.44__tar.gz → 0.2.45__tar.gz

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

@@ -2,6 +2,15 @@
 
 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.44
+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.44。**
+> **版本：0.2.45。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.44 → 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.44.**
+> **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.
 

{memleaf-0.2.44 → 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.44。**
+> **版本：0.2.45。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

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

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.44"
+__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.44 → 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.44 → 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.44 → memleaf-0.2.45}/src/memleaf/extraction_budget.py

@@ -26,8 +26,6 @@ class SinglePassBudgetBackend:
     its repair overrides the transport's configured ``llm.request_timeout``.
     """
 
-    single_pass_safe = True
-
     def __init__(
         self,
         backend: Any,
@@ -50,6 +48,18 @@ class SinglePassBudgetBackend:
     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
@@ -144,6 +154,7 @@ class ExtractionTiming:
             "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),
@@ -156,7 +167,7 @@ def aggregate_extraction_metrics(values: Iterable[Mapping[str, Any]]) -> dict[st
 
     summed = (
         "turn_count", "failed_turn_count", "over_target_turn_count",
-        "successful_within_target_count", "total_duration_ms",
+        "successful_within_target_count", "commit_accepted_count", "total_duration_ms",
         "planning_duration_ms", "commit_duration_ms",
     )
     result = {key: 0 for key in summed}

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

@@ -32,20 +32,20 @@ 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
-        # transport-timeout 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
 
 

{memleaf-0.2.44 → memleaf-0.2.45}/src/memleaf/hermes_provider/plugin.yaml

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.44
+version: 0.2.45
 description: "Hermes-native external MemoryProvider for local-first Markdown memory shared with the memleaf MCP server."
 hooks:
   - prefetch

{memleaf-0.2.44 → memleaf-0.2.45}/src/memleaf/llm/base.py

@@ -146,6 +146,7 @@ class ModelBackend(Protocol):
     parallel_safe: bool
     structured_batch_safe: bool
     single_pass_safe: bool
+    single_pass_protocol: bool
 
     def complete(
         self,
@@ -167,7 +168,6 @@ class CallableBackend:
     parallel_safe = False
     structured_batch_safe = False
     single_pass_safe = False
-
     def __init__(self, callback: Callable[..., str], *, model: str = "host"):
         if not callable(callback):
             raise TypeError("model callback must be callable")
@@ -231,7 +231,10 @@ class HTTPModelBackend:
     provider = "api"
     parallel_safe = False
     structured_batch_safe = True
-    single_pass_safe = True
+    # Protocol compatibility is provider-specific.  Generic HTTP transports
+    # must not authorize B3 merely because one complete() maps to one request.
+    single_pass_safe = False
+    single_pass_protocol = False
 
     def __init__(
         self,

memleaf-0.2.45/src/memleaf/llm/openai_compatible.py

@@ -0,0 +1,312 @@
+"""OpenAI-compatible chat-completions adapter."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Callable, Mapping, Optional
+
+from .base import DEFAULT_REQUEST_TIMEOUT, HTTPModelBackend, ModelError
+from .thinking import openai_chat_controls, requested_thinking_mode
+from ..model_capabilities import ProviderCapabilities, resolve_provider_capabilities
+
+
+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
+_REPAIR_TOKEN_MARGIN = 768
+
+
+def normalize_single_pass_token_limit(value: Any, *, default: int) -> int:
+    if isinstance(value, bool):
+        raise ValueError("single-pass token limit must be an integer")
+    if value is None or value == "":
+        return default
+    if not isinstance(value, int) or not MIN_SINGLE_PASS_MAX_TOKENS <= value <= MAX_SINGLE_PASS_MAX_TOKENS:
+        raise ValueError(
+            f"single-pass token limit must be between {MIN_SINGLE_PASS_MAX_TOKENS} and {MAX_SINGLE_PASS_MAX_TOKENS}"
+        )
+    return value
+
+
+def _repair_output_budget(prompt: str, ceiling: int) -> int:
+    """Budget a complete repaired object, never a truncated subset.
+
+    The project already uses UTF-8 bytes / 4 as a stable local token estimate
+    for maintenance.  It is not presented as an exact provider tokenizer.
+    Here we estimate only the visible previous object (the required output),
+    not the repair instructions.  If that complete object cannot fit under the
+    configured ceiling, the caller fails locally instead of dropping data.
+    """
+
+    prefix = "B3_REPAIR_INPUT\n"
+    if not prompt.startswith(prefix):
+        return ceiling
+    try:
+        payload_line = prompt[len(prefix):].split("\n", 1)[0]
+        payload = json.loads(payload_line)
+        previous = payload.get("previous_object") if isinstance(payload, Mapping) else None
+        if not isinstance(previous, Mapping):
+            return ceiling
+        visible = json.dumps(previous, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError):
+        return ceiling
+    estimated = max(1, math.ceil(len(visible) / 4)) + _REPAIR_TOKEN_MARGIN
+    if estimated > ceiling:
+        raise ModelError(
+            "single-pass repair output exceeds configured token budget",
+            code="model_failed",
+            stage="single_pass",
+        )
+    return max(MIN_SINGLE_PASS_MAX_TOKENS, estimated)
+
+
+class OpenAICompatibleBackend(HTTPModelBackend):
+    provider = "openai"
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        model: str,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        opener: Optional[Callable[..., Any]] = None,
+        json_mode: bool | None = None,
+        provider_name: str = "",
+        capabilities: ProviderCapabilities | None = None,
+        thinking: Mapping[str, Any] | None = None,
+        single_pass_primary_max_tokens: int = DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS,
+        single_pass_repair_max_tokens: int = DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS,
+    ):
+        super().__init__(base_url=base_url, api_key=api_key, model=model, timeout=timeout, opener=opener)
+        # ``provider_name``/``json_mode`` remain accepted for direct legacy
+        # construction.  Product routing supplies the already-resolved profile
+        # so credential aliases never become a capability signal.
+        if capabilities is None:
+            capabilities = resolve_provider_capabilities(
+                provider=provider_name,
+                base_url=base_url,
+            )
+        self.capabilities = capabilities
+        self.provider_family = capabilities.provider_family
+        self.provider_family_source = capabilities.source
+        self.provider_name = capabilities.provider_family  # v0.2.x compatibility attribute
+        self.json_mode = capabilities.json_object if json_mode is None else bool(json_mode)
+        self.single_pass_protocol = bool(capabilities.b3_protocol and capabilities.json_object)
+        # This adapter has one fixed POST per complete() and no hidden retry.
+        self.single_pass_safe = self.single_pass_protocol
+        self.thinking = dict(thinking) if isinstance(thinking, Mapping) else {}
+        self.single_pass_primary_max_tokens = normalize_single_pass_token_limit(
+            single_pass_primary_max_tokens,
+            default=DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS,
+        )
+        self.single_pass_repair_max_tokens = normalize_single_pass_token_limit(
+            single_pass_repair_max_tokens,
+            default=DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS,
+        )
+
+    @staticmethod
+    def _response_text_chars(value: Any) -> int:
+        if isinstance(value, str):
+            return min(len(value), 1_000_000)
+        if isinstance(value, list):
+            total = 0
+            for item in value:
+                if isinstance(item, str):
+                    total += len(item)
+                elif isinstance(item, Mapping) and isinstance(item.get("text"), str):
+                    total += len(item["text"])
+            return min(total, 1_000_000)
+        return 0
+
+    @classmethod
+    def _response_diagnostics(
+        cls,
+        value: Mapping[str, Any],
+        choice: Mapping[str, Any],
+        message: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        finish_reason = choice.get("finish_reason")
+        if not isinstance(finish_reason, str):
+            finish_reason = "unknown"
+        else:
+            finish_reason = finish_reason.casefold()
+            if finish_reason not in {
+                "stop", "length", "tool_calls", "function_call",
+                "content_filter", "insufficient_system_resource",
+            }:
+                finish_reason = "unknown"
+        usage = value.get("usage")
+        completion_tokens = usage.get("completion_tokens") if isinstance(usage, Mapping) else None
+        if not (
+            isinstance(completion_tokens, int)
+            and not isinstance(completion_tokens, bool)
+            and 0 <= completion_tokens <= 1_000_000
+        ):
+            completion_tokens = None
+        content = message.get("content")
+        reasoning = message.get("reasoning_content")
+        if reasoning is None:
+            reasoning = message.get("reasoning")
+        content_chars = cls._response_text_chars(content)
+        reasoning_chars = cls._response_text_chars(reasoning)
+        return {
+            "finish_reason": finish_reason,
+            "completion_tokens": completion_tokens,
+            "content_present": content_chars > 0,
+            "content_chars": content_chars,
+            "reasoning_present": reasoning_chars > 0,
+            "reasoning_chars": reasoning_chars,
+        }
+
+    @classmethod
+    def _usage_metrics(
+        cls,
+        value: Mapping[str, Any],
+        *,
+        thinking_metrics: Mapping[str, Any],
+        message: Mapping[str, Any] | None,
+        max_output_tokens: int | None,
+    ) -> dict[str, Any]:
+        result: dict[str, Any] = dict(thinking_metrics)
+        if isinstance(max_output_tokens, int):
+            result["max_output_tokens"] = max_output_tokens
+        usage = value.get("usage")
+        reasoning_observed = False
+        reasoning_zero_observed = False
+        if isinstance(usage, Mapping):
+            for key in (
+                "prompt_tokens", "completion_tokens", "total_tokens",
+                "prompt_cache_hit_tokens", "prompt_cache_miss_tokens",
+            ):
+                item = usage.get(key)
+                if isinstance(item, int) and not isinstance(item, bool) and 0 <= item <= 10_000_000:
+                    result[key] = item
+            prompt_details = usage.get("prompt_tokens_details")
+            cached = prompt_details.get("cached_tokens") if isinstance(prompt_details, Mapping) else None
+            if "prompt_cache_hit_tokens" not in result and isinstance(cached, int) and not isinstance(cached, bool) and 0 <= cached <= 10_000_000:
+                result["prompt_cache_hit_tokens"] = cached
+            details = usage.get("completion_tokens_details")
+            reasoning = details.get("reasoning_tokens") if isinstance(details, Mapping) else None
+            if reasoning is None:
+                reasoning = usage.get("reasoning_tokens")
+            if isinstance(reasoning, int) and not isinstance(reasoning, bool) and 0 <= reasoning <= 10_000_000:
+                result["reasoning_tokens"] = reasoning
+                reasoning_observed = reasoning > 0
+                reasoning_zero_observed = reasoning == 0
+
+        reasoning_content = None
+        if isinstance(message, Mapping):
+            reasoning_content = message.get("reasoning_content")
+            if reasoning_content is None:
+                reasoning_content = message.get("reasoning")
+        reasoning_chars = cls._response_text_chars(reasoning_content)
+        if reasoning_chars > 0:
+            reasoning_observed = True
+            result["thinking_observation_source"] = "reasoning_content"
+        elif reasoning_observed:
+            result["thinking_observation_source"] = "reasoning_tokens"
+        elif reasoning_zero_observed:
+            result["thinking_observation_source"] = "reasoning_tokens"
+        else:
+            result["thinking_observation_source"] = "unavailable"
+
+        # Request application and observed effect are independent.  In
+        # particular, sending thinking=disabled is never reported as an
+        # effective disable when the response still contains reasoning.
+        if reasoning_observed:
+            result["thinking_effective"] = "reasoning_observed"
+        elif reasoning_zero_observed:
+            result["thinking_effective"] = "no_reasoning_observed"
+        elif result.get("thinking_applied") is True:
+            result["thinking_effective"] = "unknown"
+        return result
+
+    def _single_pass_budget(self, prompt: str) -> int | None:
+        if prompt.startswith("B3_REPAIR_INPUT\n"):
+            return _repair_output_budget(prompt, self.single_pass_repair_max_tokens)
+        return self.single_pass_primary_max_tokens
+
+    def complete(self, prompt: str, *, system: str = "", purpose: str = "", temperature: float = 0.0) -> str:
+        self._set_call_metrics({})
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        requested = requested_thinking_mode(self.thinking, purpose)
+        controls, thinking_metrics, omit_temperature = openai_chat_controls(
+            self.provider_family, self.model, requested
+        )
+        payload: dict[str, Any] = {"model": self.model, "messages": messages}
+        if not omit_temperature:
+            payload["temperature"] = temperature
+        payload.update(controls)
+        if self.json_mode and purpose in {"gate", "summarize", "compact", "single_pass"}:
+            payload["response_format"] = {"type": "json_object"}
+
+        max_output_tokens: int | None = None
+        if purpose == "single_pass" and self.single_pass_protocol:
+            max_output_tokens = self._single_pass_budget(prompt)
+            field = self.capabilities.output_token_field
+            if isinstance(field, str) and field and isinstance(max_output_tokens, int):
+                payload[field] = max_output_tokens
+
+        value = self._post_json(
+            self.base_url + "/chat/completions",
+            payload,
+            {"Authorization": f"Bearer {self.api_key}"},
+            stage=purpose,
+        )
+        choices = value.get("choices")
+        if not isinstance(choices, list) or not choices or not isinstance(choices[0], Mapping):
+            self._set_call_metrics(self._usage_metrics(
+                value, thinking_metrics=thinking_metrics, message=None,
+                max_output_tokens=max_output_tokens,
+            ))
+            raise ModelError(
+                "model response has no choices",
+                code="model_invalid_response",
+                stage=purpose,
+                validation_reason="response_shape",
+            )
+        message = choices[0].get("message")
+        if not isinstance(message, Mapping):
+            self._set_call_metrics(self._usage_metrics(
+                value, thinking_metrics=thinking_metrics, message=None,
+                max_output_tokens=max_output_tokens,
+            ))
+            raise ModelError(
+                "model response has no message",
+                code="model_invalid_response",
+                stage=purpose,
+                validation_reason="response_shape",
+            )
+        diagnostics = self._response_diagnostics(value, choices[0], message)
+        self._set_call_metrics(self._usage_metrics(
+            value, thinking_metrics=thinking_metrics, message=message,
+            max_output_tokens=max_output_tokens,
+        ))
+        if diagnostics.get("finish_reason") == "length":
+            raise ModelError(
+                "model response was truncated",
+                code="model_invalid_response",
+                stage=purpose,
+                validation_reason="response_shape",
+            ).with_response_diagnostics(diagnostics)
+        try:
+            return self._text(message.get("content"), stage=purpose)
+        except ModelError as error:
+            error.with_response_diagnostics(diagnostics)
+            raise
+
+
+__all__ = [
+    "DEFAULT_SINGLE_PASS_PRIMARY_MAX_TOKENS",
+    "DEFAULT_SINGLE_PASS_REPAIR_MAX_TOKENS",
+    "MIN_SINGLE_PASS_MAX_TOKENS",
+    "MAX_SINGLE_PASS_MAX_TOKENS",
+    "OpenAICompatibleBackend",
+    "normalize_single_pass_token_limit",
+]