turnsafe 0.1.0__py3-none-any.whl

turnsafe/__init__.py

@@ -0,0 +1,66 @@
+"""turnsafe: validate, repair and trim LLM chat history without orphaning tool calls.
+
+    import turnsafe
+
+    report = turnsafe.validate(messages)           # what the API would reject, and why
+    messages = turnsafe.repair(messages)           # fix orphaned / missing / misplaced results
+    messages = turnsafe.fit(messages, 100_000)     # trim whole turns to a token budget
+
+Works on plain OpenAI Chat Completions and Anthropic Messages dicts. No
+dependencies, no framework, no network.
+"""
+
+from ._providers import detect as detect_provider
+from ._types import (
+    DUPLICATE_TOOL_CALL_ID,
+    DUPLICATE_TOOL_RESULT,
+    EMPTY_CONTENT,
+    FIRST_MESSAGE_NOT_USER,
+    MISPLACED_TOOL_RESULT,
+    ORPHAN_TOOL_RESULT,
+    SYSTEM_IN_MESSAGES,
+    TOOL_RESULT_NOT_FIRST,
+    UNANSWERED_TOOL_CALL,
+    ContextBudgetError,
+    Fix,
+    InvalidHistoryError,
+    ProviderDetectionError,
+    Report,
+    TurnsafeError,
+    Violation,
+)
+from .fit import FitResult, fit, fit_detailed
+from .repair import DEFAULT_PLACEHOLDER, repair, repair_detailed
+from .tokens import approx_tokens
+from .validate import validate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_PLACEHOLDER",
+    "DUPLICATE_TOOL_CALL_ID",
+    "DUPLICATE_TOOL_RESULT",
+    "EMPTY_CONTENT",
+    "FIRST_MESSAGE_NOT_USER",
+    "MISPLACED_TOOL_RESULT",
+    "ORPHAN_TOOL_RESULT",
+    "SYSTEM_IN_MESSAGES",
+    "TOOL_RESULT_NOT_FIRST",
+    "UNANSWERED_TOOL_CALL",
+    "ContextBudgetError",
+    "FitResult",
+    "Fix",
+    "InvalidHistoryError",
+    "ProviderDetectionError",
+    "Report",
+    "TurnsafeError",
+    "Violation",
+    "__version__",
+    "approx_tokens",
+    "detect_provider",
+    "fit",
+    "fit_detailed",
+    "repair",
+    "repair_detailed",
+    "validate",
+]

turnsafe/_match.py

@@ -0,0 +1,126 @@
+"""Pair every tool call with its tool result.
+
+``validate`` reports from this and ``repair`` rebuilds from it, so the two can
+never disagree about which result answers which call.
+
+Matching rule: a call made by an assistant turn (one message, or for
+Anthropic a run of consecutive assistant messages, which the API merges) is
+answered by the first result with its id that comes after the turn and before
+the next turn that calls the same id again. A result inside the provider's
+allowed zone (see ``Adapter.zone``) is correctly placed; one elsewhere is
+misplaced but recoverable. Further results for an answered call are
+duplicates, and results that answer nothing are orphans.
+
+Every result and call is visited a constant number of times, so matching is
+linear in the size of the history.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from ._providers import Adapter
+from ._types import Message
+
+# A result item's location: (message index, position among that message's results).
+Loc = tuple[int, int]
+
+
+@dataclass
+class Match:
+    # assistant turn start -> call ids in order, duplicates removed
+    calls: dict[int, list[str]] = field(default_factory=dict)
+    # assistant turn start -> indices of the assistant messages in that turn
+    runs: dict[int, list[int]] = field(default_factory=dict)
+    # assistant index -> call id -> result location
+    answered: dict[int, dict[str, Loc]] = field(default_factory=dict)
+    # results that answer a call but sit outside the allowed zone
+    misplaced: set[Loc] = field(default_factory=set)
+    # assistant index -> call ids with no result anywhere in the window
+    missing: dict[int, list[str]] = field(default_factory=dict)
+    # (assistant index, call id) for ids repeated inside one message
+    duplicate_calls: list[tuple[int, str]] = field(default_factory=list)
+    # locations of second and later results for an already-answered call
+    duplicates: set[Loc] = field(default_factory=set)
+    # locations of results that answer nothing
+    orphans: set[Loc] = field(default_factory=set)
+    # result ids by location, for reporting
+    result_ids: dict[Loc, str] = field(default_factory=dict)
+
+
+def match(adapter: Adapter, msgs: Sequence[Message]) -> Match:
+    m = Match()
+    results_by_id: dict[str, list[Loc]] = {}
+    for j, msg in enumerate(msgs):
+        for pos, (rid, _) in enumerate(adapter.result_items(msg)):
+            m.result_ids[(j, pos)] = rid
+            results_by_id.setdefault(rid, []).append((j, pos))
+
+    runs: list[list[int]] = []
+    for i, msg in enumerate(msgs):
+        if msg.get("role") != "assistant":
+            continue
+        if runs and runs[-1][-1] == i - 1 and adapter.merges_assistant_runs:
+            runs[-1].append(i)
+        else:
+            runs.append([i])
+
+    turn_ids: list[list[str]] = []
+    calls_by_id: dict[str, list[int]] = {}
+    for n, run in enumerate(runs):
+        ids: list[str] = []
+        seen: set[str] = set()
+        for k in run:
+            for cid in adapter.call_ids(msgs[k]):
+                if cid in seen:
+                    m.duplicate_calls.append((run[0], cid))
+                else:
+                    seen.add(cid)
+                    ids.append(cid)
+                    calls_by_id.setdefault(cid, []).append(n)
+        turn_ids.append(ids)
+
+    claimed: set[Loc] = set()
+    result_ptr: dict[str, int] = {}
+    call_ptr: dict[str, int] = {}
+    for n, run in enumerate(runs):
+        ids = turn_ids[n]
+        if not ids:
+            continue
+        i, end = run[0], run[-1]
+        m.calls[i] = ids
+        m.runs[i] = run
+        zone = set(adapter.zone(msgs, end))
+        answered: dict[str, Loc] = {}
+        for cid in ids:
+            # Stop at the next turn that reuses this id: its results are its own.
+            call_ptr[cid] = call_ptr.get(cid, 0) + 1
+            later = calls_by_id[cid][call_ptr[cid] :]
+            limit = runs[later[0]][0] if later else len(msgs)
+
+            found = results_by_id.get(cid, [])
+            k = result_ptr.get(cid, 0)
+            while k < len(found) and found[k][0] <= end:
+                k += 1  # before the call: left as orphans
+            locs = []
+            while k < len(found) and found[k][0] < limit:
+                locs.append(found[k])
+                k += 1
+            result_ptr[cid] = k
+            if not locs:
+                m.missing.setdefault(i, []).append(cid)
+                continue
+            # Prefer a correctly placed result over a misplaced one.
+            best = next((loc for loc in locs if loc[0] in zone), locs[0])
+            answered[cid] = best
+            if best[0] not in zone:
+                m.misplaced.add(best)
+            for loc in locs:
+                claimed.add(loc)
+                if loc != best:
+                    m.duplicates.add(loc)
+        m.answered[i] = answered
+
+    m.orphans = {loc for loc in m.result_ids if loc not in claimed}
+    return m

turnsafe/_providers.py

@@ -0,0 +1,351 @@
+"""Per-provider knowledge: where tool calls and tool results live in a message.
+
+Everything format-specific is here. ``validate``, ``repair`` and ``fit`` only
+talk to the ``Adapter`` interface, so adding a provider means adding a class.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+from ._types import Message, Provider, ProviderDetectionError
+
+
+def to_dict(obj: Any, what: str = "message") -> dict[str, Any]:
+    """Turn a message or block into a plain dict.
+
+    Accepts mappings and SDK objects with ``model_dump`` (openai / anthropic
+    pydantic models). ``None`` fields are dropped, which both APIs accept.
+    """
+    if isinstance(obj, Mapping):
+        return dict(obj)
+    dump = getattr(obj, "model_dump", None)
+    if callable(dump):
+        result = dump(exclude_none=True)
+        if isinstance(result, dict):
+            return result
+    raise TypeError(
+        f"Expected a {what} dict (or an SDK object with model_dump()), got {type(obj).__name__}"
+    )
+
+
+def normalize(messages: Iterable[Any]) -> list[Message]:
+    """Deep-copy the history into plain dicts so callers' objects are never mutated.
+
+    Tuples become lists, and tool call ids are checked: a call or result
+    without a usable id would silently escape every rule.
+    """
+    if isinstance(messages, (str, bytes, Mapping)):
+        raise TypeError("messages must be a list of message dicts")
+    out: list[Message] = []
+    for i, raw in enumerate(messages):
+        msg = copy.deepcopy(to_dict(raw))
+        content = msg.get("content")
+        if isinstance(content, (list, tuple)):
+            msg["content"] = [to_dict(block, "content block") for block in content]
+            for k, block in enumerate(msg["content"]):
+                if block.get("type") in ("tool_use", "server_tool_use", "mcp_tool_use"):
+                    _check_id(block.get("id"), f"messages[{i}].content[{k}].id")
+                elif block.get("type") == "tool_result":
+                    _check_id(block.get("tool_use_id"), f"messages[{i}].content[{k}].tool_use_id")
+        calls = msg.get("tool_calls")
+        if isinstance(calls, (list, tuple)):
+            msg["tool_calls"] = [to_dict(call, "tool call") for call in calls]
+            for k, call in enumerate(msg["tool_calls"]):
+                _check_id(call.get("id"), f"messages[{i}].tool_calls[{k}].id")
+        if msg.get("role") == "tool":
+            _check_id(msg.get("tool_call_id"), f"messages[{i}].tool_call_id")
+        out.append(msg)
+    return out
+
+
+def _check_id(value: Any, where: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{where} must be a non-empty string, got {value!r}")
+
+
+class Adapter:
+    """How one provider's message format stores tool calls and results.
+
+    A "result item" is whatever unit carries one tool result: a whole
+    ``role: tool`` message for OpenAI, a ``tool_result`` block for Anthropic.
+    """
+
+    name: Provider
+    # Whether the API treats consecutive assistant messages as one turn.
+    merges_assistant_runs = False
+
+    def call_ids(self, msg: Message) -> list[str]:
+        """Ids of client tool calls made by this message (assistant only)."""
+        raise NotImplementedError
+
+    def result_items(self, msg: Message) -> list[tuple[str, Any]]:
+        """(tool_call_id, item) for each tool result carried by this message."""
+        raise NotImplementedError
+
+    def zone(self, messages: Sequence[Message], i: int) -> list[int]:
+        """Indices where results for the calls in ``messages[i]`` are allowed."""
+        raise NotImplementedError
+
+    def is_turn_start(self, msg: Message) -> bool:
+        """True for a user message that starts a new turn (not just tool results)."""
+        raise NotImplementedError
+
+    def placeholder(self, tool_call_id: str, text: str) -> Any:
+        """A synthetic result item for a call whose real result is missing."""
+        raise NotImplementedError
+
+    def strip_calls(self, msg: Message, ids: set[str]) -> Message | None:
+        """``msg`` without the given calls, or None if nothing meaningful is left."""
+        raise NotImplementedError
+
+    def emit_group(
+        self, assistants: list[Message], items: list[Any], zone_msgs: list[Message]
+    ) -> list[Message]:
+        """The assistant turn followed by messages that carry ``items``.
+
+        ``zone_msgs`` are the input messages in the assistant's zone. Their
+        result items are replaced by ``items``; everything else they hold,
+        content and keys, must be kept.
+        """
+        raise NotImplementedError
+
+    def rename_call(self, msg: Message, old: str, new: str) -> Message:
+        """``msg`` with the tool call ``old`` renamed to ``new``."""
+        raise NotImplementedError
+
+    def rename_result(self, item: Any, new: str) -> Any:
+        """A copy of result ``item`` answering ``new`` instead."""
+        raise NotImplementedError
+
+    def without_results(self, msg: Message) -> Message | None:
+        """``msg`` with every tool result removed, or None if it becomes empty."""
+        raise NotImplementedError
+
+
+class OpenAIAdapter(Adapter):
+    """OpenAI Chat Completions (``role: tool`` messages answer ``tool_calls``)."""
+
+    name: Provider = "openai"
+
+    def call_ids(self, msg: Message) -> list[str]:
+        if msg.get("role") != "assistant":
+            return []
+        calls = msg.get("tool_calls") or []
+        return [c["id"] for c in calls if isinstance(c, dict) and isinstance(c.get("id"), str)]
+
+    def result_items(self, msg: Message) -> list[tuple[str, Any]]:
+        if msg.get("role") == "tool":
+            return [(str(msg.get("tool_call_id", "")), msg)]
+        return []
+
+    def zone(self, messages: Sequence[Message], i: int) -> list[int]:
+        out = []
+        j = i + 1
+        while j < len(messages) and messages[j].get("role") == "tool":
+            out.append(j)
+            j += 1
+        return out
+
+    def is_turn_start(self, msg: Message) -> bool:
+        return msg.get("role") == "user"
+
+    def placeholder(self, tool_call_id: str, text: str) -> Any:
+        return {"role": "tool", "tool_call_id": tool_call_id, "content": text}
+
+    def strip_calls(self, msg: Message, ids: set[str]) -> Message | None:
+        out = dict(msg)
+        kept = [c for c in msg.get("tool_calls") or [] if c.get("id") not in ids]
+        if kept:
+            out["tool_calls"] = kept
+            return out
+        out.pop("tool_calls", None)
+        out.pop("parallel_tool_calls", None)
+        if _is_empty(out.get("content")) and not out.get("audio") and not out.get("refusal"):
+            return None
+        return out
+
+    def emit_group(
+        self, assistants: list[Message], items: list[Any], zone_msgs: list[Message]
+    ) -> list[Message]:
+        # The zone only ever holds tool messages, which are all in ``items`` or dropped.
+        return [*assistants, *items]
+
+    def rename_call(self, msg: Message, old: str, new: str) -> Message:
+        calls = [{**c, "id": new} if c.get("id") == old else c for c in msg["tool_calls"]]
+        return {**msg, "tool_calls": calls}
+
+    def rename_result(self, item: Any, new: str) -> Any:
+        return {**item, "tool_call_id": new}
+
+    def without_results(self, msg: Message) -> Message | None:
+        return None if msg.get("role") == "tool" else msg
+
+
+# Anthropic blocks that pair with a later client-side tool_result. Server tool
+# blocks (server_tool_use, web_search_tool_result, mcp_tool_use, ...) are
+# answered inside the same assistant message, so they are left alone.
+_ANTHROPIC_CALL = "tool_use"
+_ANTHROPIC_RESULT = "tool_result"
+
+
+def _blocks(msg: Message) -> list[Any]:
+    content = msg.get("content")
+    return content if isinstance(content, list) else []
+
+
+class AnthropicAdapter(Adapter):
+    """Anthropic Messages (``tool_result`` blocks answer ``tool_use`` blocks)."""
+
+    name: Provider = "anthropic"
+    # "Consecutive user or assistant turns in your request will be combined
+    # into a single turn." https://platform.claude.com/docs/en/api/messages
+    merges_assistant_runs = True
+
+    def call_ids(self, msg: Message) -> list[str]:
+        if msg.get("role") != "assistant":
+            return []
+        return [
+            b["id"]
+            for b in _blocks(msg)
+            if isinstance(b, dict)
+            and b.get("type") == _ANTHROPIC_CALL
+            and isinstance(b.get("id"), str)
+        ]
+
+    def result_items(self, msg: Message) -> list[tuple[str, Any]]:
+        if msg.get("role") != "user":
+            return []
+        return [
+            (str(b.get("tool_use_id", "")), b)
+            for b in _blocks(msg)
+            if isinstance(b, dict) and b.get("type") == _ANTHROPIC_RESULT
+        ]
+
+    def zone(self, messages: Sequence[Message], i: int) -> list[int]:
+        # The API merges consecutive user messages into one turn before
+        # checking, so results may be spread over the whole run.
+        out = []
+        j = i + 1
+        while j < len(messages) and messages[j].get("role") == "user":
+            out.append(j)
+            j += 1
+        return out
+
+    def is_turn_start(self, msg: Message) -> bool:
+        return msg.get("role") == "user" and not self.result_items(msg)
+
+    def placeholder(self, tool_call_id: str, text: str) -> Any:
+        return {
+            "type": "tool_result",
+            "tool_use_id": tool_call_id,
+            "content": text,
+            "is_error": True,
+        }
+
+    def strip_calls(self, msg: Message, ids: set[str]) -> Message | None:
+        kept = [
+            b for b in _blocks(msg) if not (b.get("type") == _ANTHROPIC_CALL and b.get("id") in ids)
+        ]
+        # Thinking blocks alone are not a meaningful assistant turn.
+        if not any(b.get("type") not in ("thinking", "redacted_thinking") for b in kept):
+            return None
+        return {**msg, "content": kept}
+
+    def emit_group(
+        self, assistants: list[Message], items: list[Any], zone_msgs: list[Message]
+    ) -> list[Message]:
+        # One user message: every tool_result first, then whatever else the zone
+        # held, in order. Other keys from every zone message are kept (first wins).
+        if not items:
+            kept = [self.without_results(z) for z in zone_msgs]
+            return [*assistants, *(z for z in kept if z is not None)]
+        base: Message = {}
+        rest: list[Any] = []
+        for msg in zone_msgs:
+            for key, value in msg.items():
+                if key != "content":
+                    base.setdefault(key, value)
+            content = msg.get("content")
+            if isinstance(content, str):
+                rest += [{"type": "text", "text": content}] if content else []
+            elif isinstance(content, list):
+                rest += [b for b in content if b.get("type") != _ANTHROPIC_RESULT]
+        base.setdefault("role", "user")
+        return [*assistants, {**base, "content": [*items, *rest]}]
+
+    def rename_call(self, msg: Message, old: str, new: str) -> Message:
+        content = [
+            {**b, "id": new} if b.get("type") == _ANTHROPIC_CALL and b.get("id") == old else b
+            for b in _blocks(msg)
+        ]
+        return {**msg, "content": content}
+
+    def rename_result(self, item: Any, new: str) -> Any:
+        return {**item, "tool_use_id": new}
+
+    def without_results(self, msg: Message) -> Message | None:
+        if not self.result_items(msg):
+            return msg
+        kept = [b for b in _blocks(msg) if b.get("type") != _ANTHROPIC_RESULT]
+        if not kept:
+            return None
+        return {**msg, "content": kept}
+
+
+def _is_empty(content: Any) -> bool:
+    return content is None or content == "" or content == []
+
+
+ADAPTERS: dict[str, Adapter] = {"openai": OpenAIAdapter(), "anthropic": AnthropicAdapter()}
+
+_OPENAI_ROLES = {"tool", "developer", "function"}
+_ANTHROPIC_BLOCKS = {
+    "tool_use",
+    "tool_result",
+    "thinking",
+    "redacted_thinking",
+    "server_tool_use",
+    "web_search_tool_result",
+    "mcp_tool_use",
+    "mcp_tool_result",
+}
+
+
+def detect(messages: Sequence[Message]) -> Provider:
+    """Guess the message format from tool-call markers.
+
+    Plain text histories with no markers are reported as ``"openai"``; the
+    two formats validate identically when there are no tools involved, except
+    for Anthropic's content rules, so pass ``provider=`` when you know it.
+    """
+    # "system" is deliberately not an OpenAI signal: in an Anthropic history it
+    # is a mistake that validate() should report, not a reason to give up.
+    openai = anthropic = False
+    for msg in messages:
+        if (
+            msg.get("role") in _OPENAI_ROLES
+            or msg.get("tool_calls")
+            or msg.get("tool_call_id") is not None
+        ):
+            openai = True
+        if any(isinstance(b, dict) and b.get("type") in _ANTHROPIC_BLOCKS for b in _blocks(msg)):
+            anthropic = True
+    if openai and anthropic:
+        raise ProviderDetectionError(
+            "History mixes OpenAI and Anthropic tool formats; pass provider= explicitly."
+        )
+    return "anthropic" if anthropic else "openai"
+
+
+def get_adapter(provider: str, messages: Sequence[Message]) -> Adapter:
+    if provider == "auto":
+        provider = detect(messages)
+    try:
+        return ADAPTERS[provider]
+    except KeyError:
+        raise ValueError(
+            f"Unknown provider {provider!r}; expected 'openai', 'anthropic' or 'auto'."
+        ) from None

turnsafe/_thinking.py

@@ -0,0 +1,99 @@
+"""Keep Anthropic thinking blocks valid after the history has been changed.
+
+On models with thinking-block prefix binding (Claude Fable 5.1 and Opus 5.5,
+enforced by default for accounts created on or after 2026-08-31), a replayed
+``thinking`` or ``redacted_thinking`` block is only valid while every message
+before it is unchanged. Trimming from the front, dropping a message or
+editing one invalidates that block and every later one, and the API answers
+"Invalid `signature` in `thinking` block. The block is bound to a different
+conversation."
+
+The documented recovery is to remove the thinking blocks from the first
+changed position onward, leaving everything else in place, or to set
+``prefix_mismatch_behavior: "drop_block"`` and let the API drop them.
+https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting
+
+Models without prefix binding differ: they want the latest assistant turn's
+thinking replayed unchanged, and manual extended thinking requires it in a
+tool loop. That is why ``"keep"`` is the default and stripping is opt-in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+
+from ._types import Message
+
+ThinkingPolicy = Literal["strip_after_change", "keep"]
+THINKING_BLOCKS = ("thinking", "redacted_thinking")
+
+
+def first_change(before: Sequence[Message], after: Sequence[Message]) -> int:
+    """Index of the first message in ``after`` that differs from ``before``."""
+    for n, (a, b) in enumerate(zip(before, after, strict=False)):
+        if a != b:
+            return n
+    return min(len(before), len(after))
+
+
+def strip_after_change(
+    before: Sequence[Message], after: list[Message], src: Sequence[int] | None = None
+) -> tuple[list[Message], list[int]]:
+    """Remove every thinking block in ``after`` that follows its first change.
+
+    ``src[n]`` is the index in ``before`` that ``after[n]`` was derived from.
+    When the first changed message is an edited version of the message at the
+    same position, thinking blocks that come before its first changed block are
+    kept: nothing before them changed.
+    """
+    n = first_change(before, after)
+    if n >= len(after):
+        return after, []
+    msg = after[n]
+    content = msg.get("content")
+    same = src is not None and n < len(src) and src[n] == n and n < len(before)
+    old = before[n].get("content") if same else None
+    if msg.get("role") == "assistant" and isinstance(content, list) and isinstance(old, list):
+        b = next(
+            (k for k, (x, y) in enumerate(zip(old, content, strict=False)) if x != y),
+            min(len(old), len(content)),
+        )
+        kept = content[:b] + [x for x in content[b:] if x.get("type") not in THINKING_BLOCKS]
+        head: list[Message] = after[:n]
+        touched = [n] if len(kept) != len(content) else []
+        if kept:
+            head.append({**msg, "content": kept})
+        rest, more = strip_from(after[n + 1 :], 0)
+        return head + rest, touched + [n + 1 + k for k in more]
+    return strip_from(after, n)
+
+
+def strip_from(msgs: list[Message], start: int) -> tuple[list[Message], list[int]]:
+    """Remove thinking blocks from assistant messages at ``start`` and later.
+
+    Returns the new list and the output positions of the messages that lost
+    blocks. An assistant message left with nothing but thinking is dropped;
+    its position is reported too.
+    """
+    out: list[Message] = msgs[:start]
+    touched: list[int] = []
+    for n in range(start, len(msgs)):
+        msg = msgs[n]
+        content = msg.get("content")
+        if msg.get("role") != "assistant" or not isinstance(content, list):
+            out.append(msg)
+            continue
+        kept = [b for b in content if b.get("type") not in THINKING_BLOCKS]
+        if len(kept) == len(content):
+            out.append(msg)
+            continue
+        touched.append(n)
+        if kept:
+            out.append({**msg, "content": kept})
+    return out, touched
+
+
+def check_policy(thinking: str) -> None:
+    if thinking not in ("strip_after_change", "keep"):
+        raise ValueError(f"thinking must be 'strip_after_change' or 'keep', got {thinking!r}")