turnsafe 0.1.0__tar.gz

turnsafe-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+dist/
+build/
+.env
+.DS_Store

turnsafe-0.1.0/AGENT.md

@@ -0,0 +1,99 @@
+# AGENT.md
+
+A guide for AI coding agents and human contributors working on `turnsafe`.
+
+## What this project is
+
+`turnsafe` is a zero-dependency Python library that validates, repairs and trims LLM chat
+histories. Its purpose is to make sure a tool call is never separated from its result. It works on
+plain provider message dicts: OpenAI Chat Completions and Anthropic Messages in v0.1.
+
+Why it exists, and what was rejected in its favour, is in [docs/research.md](docs/research.md).
+Every provider rule is listed with its source in [docs/rules.md](docs/rules.md).
+
+## Commands
+
+```bash
+uv venv && uv pip install -e '.[dev]'   # set up
+pytest -q                                # all offline tests, including property tests (~2 s)
+mypy                                     # strict, src only
+ruff check src tests && ruff format src tests
+TURNSAFE_LIVE=1 pytest tests/test_live.py   # real API contract tests; needs API keys
+python -m build && twine check dist/*       # build and check the release artefacts
+```
+
+A change is done only when `pytest`, `mypy` and `ruff check` all pass.
+
+## Layout
+
+| File | Responsibility |
+|---|---|
+| `src/turnsafe/_providers.py` | **All** format-specific knowledge. It has one `Adapter` per provider: where calls and results live, the allowed "zone" for results, what starts a turn, and how to build a placeholder. It also contains `normalize()` (deep copy, SDK objects to dicts) and `detect()`. |
+| `src/turnsafe/_match.py` | Pairs every call with its result. `validate` and `repair` both use it, so they cannot disagree. |
+| `src/turnsafe/validate.py` | Turns a `Match` plus provider-only rules into `Violation`s. |
+| `src/turnsafe/repair.py` | Rebuilds the history from a `Match`. |
+| `src/turnsafe/fit.py` | Splits the history into turns and drops whole turns, oldest first. |
+| `src/turnsafe/_thinking.py` | Opt-in removal of Anthropic thinking blocks after the first change (prefix binding). |
+| `src/turnsafe/tokens.py` | Offline token estimate. |
+| `src/turnsafe/_types.py` | Public dataclasses, violation codes and exceptions. |
+| `tests/builders.py` | Short constructors (`ou`, `oa`, `ot`, `au`, `aa`, `use`, `res`, `thinking`). Use them in tests. |
+| `tests/test_properties.py` | Hypothesis tests of the invariants below. |
+
+## Invariants: never break these
+
+The property tests check all of them. If a change needs one relaxed, stop and ask a
+maintainer first.
+
+1. **Pure.** No public function mutates its input. `normalize()` deep-copies first.
+2. **Repaired output validates.** `validate(repair(x))` has no errors except
+   `system_in_messages` on the first message, which only the caller can move.
+3. **Fixed point.** If `validate(x)` has no violations, then `repair(x) == x` and there are no fixes.
+4. **Idempotent.** `repair(repair(x)) == repair(x)`.
+5. **Assistant messages are sacred.** With the default `thinking="keep"`, `repair()` never
+   edits an assistant message, except to remove a repeated tool call id or under
+   `on_missing="strip"`. With `thinking="strip_after_change"`, the only extra edit is removing
+   thinking blocks that come after the first changed block, because on models with prefix
+   binding those blocks are invalid. Read the thinking section of `docs/rules.md` before
+   touching this.
+6. **Fitted output validates, and is a suffix.** `fit()` output is valid, and apart from pinned
+   system messages and an optional pinned first turn, it is a contiguous tail of the input
+   (with `thinking="strip_after_change"`, thinking blocks are removed once anything was dropped).
+   It never splits a turn.
+7. **Unknown content passes through.** Blocks and keys that turnsafe doesn't understand are
+   copied unchanged, never dropped.
+8. **No runtime dependencies.** Only the standard library. SDKs may be used in tests only.
+9. **Linear time.** Matching, validation, repair and fit are linear in the history size.
+   `tests/test_regressions.py` has timing guards for the pathological cases (many orphans,
+   reused ids, thousands of parallel calls). Don't add per-turn scans over the whole history.
+
+## Rules for changing provider behaviour
+
+- **Every rule needs a source.** Add a row to `docs/rules.md` with the official doc URL and, where
+  possible, the exact API error string. Don't encode a rule you can't source. If a rule is only
+  sometimes enforced, make it a `warning`.
+- **Put the rule in the right place.** Format knowledge goes in an `Adapter` method. A
+  provider-only check that isn't about pairing goes in `validate.py` (see
+  `_anthropic_rules`). Don't add `if provider == ...` branches to `_match.py` or `fit.py`.
+- **Add a live case.** When you add or change a rule, add a case to `tests/test_live.py` that
+  the real API rejects before repair and accepts after.
+- **Adding a provider** (Responses, Gemini) means writing a new `Adapter` subclass, adding it
+  to `ADAPTERS`, adding detection markers, adding a strategy in `test_properties.py`, and adding
+  a section in `docs/rules.md`.
+
+## Style
+
+- Match the existing code: small functions, type hints everywhere (`mypy --strict`), docstrings
+  on public functions, and comments only where the reason isn't obvious.
+- Public API changes must update `__all__`, `README.md` and `CHANGELOG.md`.
+- Violation codes and `Fix.action` strings are public API. Don't rename them outside a
+  major release.
+- Error and violation messages say what is wrong and where. `InvalidHistoryError` points the
+  user to `repair()`.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `src/turnsafe/__init__.py`.
+2. Move the "Unreleased" entries in `CHANGELOG.md` under the new version.
+3. Tag `vX.Y.Z` and push the tag. `.github/workflows/release.yml` builds the package and
+   publishes it to PyPI through trusted publishing. Never publish from a laptop with a
+   long-lived token.

turnsafe-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- `validate()`: checks an OpenAI Chat Completions or Anthropic Messages history and returns a
+  `Report` of typed `Violation`s. The report says what the API would reject, where, and for
+  which tool call.
+- `repair()` and `repair_detailed()`: rebuild a valid history. They move misplaced results,
+  drop orphaned and duplicate results, and add placeholder results for unanswered calls (or
+  remove those calls when `on_missing="strip"`). They also fix the Anthropic block-order and
+  empty-content rules.
+- `fit()` and `fit_detailed()`: trim a history to a token budget by dropping whole turns, so a
+  tool call is never split from its results. Options: `keep_system`, `keep_first_turn` and a
+  custom `counter`.
+- `thinking=` on `repair()` and `fit()`. The default `"keep"` never touches Anthropic thinking
+  blocks. `"strip_after_change"` removes them from the first changed block onward, for Claude
+  models with thinking-block prefix binding (Fable 5.1, Opus 5.5).
+- Anthropic rules verified against the docs on 2026-09-28:
+  - Consecutive user messages, and consecutive assistant messages, are each treated as one turn.
+  - `tool_use` ids must be unique across the history.
+  - Blank `tool_result` content and empty assistant content are accepted.
+  - A mid-conversation `system` message is a warning; it's an error only as the first message.
+- A result that ended up after an unrelated assistant message is moved back to its call instead
+  of being replaced by a placeholder. The search stops at the next call that reuses the same id.
+- Tool call and result ids must be non-empty strings. Anything else raises a `ValueError` that
+  names the position, instead of silently escaping the rules.
+- Validation, repair and trimming are linear in the size of the history, including for
+  histories with many orphaned results, reused ids or thousands of parallel calls.
+- `approx_tokens()`: an offline token estimate that counts images as images.
+- `detect_provider()` and `provider="auto"`.
+- Accepts SDK message objects that have `model_dump()`.
+- Property-based tests for the invariants listed in `AGENT.md`, and opt-in live contract tests
+  against both APIs.

turnsafe-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to turnsafe
+
+Thanks for helping. This guide covers setting up, what a good change looks like, and how to
+report a provider rule turnsafe gets wrong.
+
+## Set up
+
+```bash
+git clone https://github.com/Yasir-Khan-7/turnsafe && cd turnsafe
+uv venv && uv pip install -e '.[dev]'     # or: python -m venv .venv && pip install -e '.[dev]'
+pytest -q                                 # fully offline, about 3 seconds
+```
+
+## Before you open a pull request
+
+```bash
+pytest -q
+mypy
+ruff check src tests && ruff format src tests
+```
+
+CI runs all of these on Python 3.10 to 3.14.
+
+## What a good change looks like
+
+- **Tests.** Every behaviour change comes with a test. If it touches `repair()` or `fit()`, also
+  check that the property tests in `tests/test_properties.py` still hold, or extend their
+  generators.
+- **Cited rules.** Every provider rule needs a source. Add it to `docs/rules.md` with the
+  official docs link, and where possible the exact API error text. If you can't source a rule,
+  make it a warning, not an error.
+- **Format code lives in one place.** Format-specific code goes in an `Adapter` in
+  `src/turnsafe/_providers.py`, not in `if provider == ...` branches elsewhere.
+- **Stable names.** Public names, violation codes and `Fix.action` strings are stable API. Note
+  any change to them in `CHANGELOG.md`.
+
+The invariants the code must keep are listed in [AGENT.md](AGENT.md#invariants-never-break-these).
+
+## Reporting a wrong rule
+
+The most useful issue you can open includes:
+1. The exact API error text.
+2. The model and platform: first-party API, Bedrock, Vertex or a gateway.
+3. The smallest `messages` list that reproduces it. Redact the content, since only the
+   structure matters.
+
+## Live tests
+
+`tests/test_live.py` sends real requests to check that repaired histories are accepted. It
+costs a few tokens and is skipped by default:
+
+```bash
+TURNSAFE_LIVE=1 OPENAI_API_KEY=... ANTHROPIC_API_KEY=... pytest tests/test_live.py
+```

turnsafe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yasir Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

turnsafe-0.1.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.5
+Name: turnsafe
+Version: 0.1.0
+Summary: Validate, repair and trim LLM chat history without orphaning tool calls. Fixes 'tool_use ids were found without tool_result blocks' and 'messages with role tool must be a response to a preceeding message with tool_calls'.
+Project-URL: Homepage, https://github.com/Yasir-Khan-7/turnsafe
+Project-URL: Documentation, https://github.com/Yasir-Khan-7/turnsafe#readme
+Project-URL: Issues, https://github.com/Yasir-Khan-7/turnsafe/issues
+Project-URL: Changelog, https://github.com/Yasir-Khan-7/turnsafe/blob/main/CHANGELOG.md
+Author: Yasir Khan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,anthropic,chat-history,claude,context-window,function-calling,llm,openai,tool-calling,tool_result,tool_use,trim-messages
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# turnsafe
+
+**Never send a broken chat history to an LLM again.**
+
+Validate, repair and trim OpenAI and Anthropic message lists, without ever separating a tool
+call from its result.
+
+[![CI](https://github.com/Yasir-Khan-7/turnsafe/actions/workflows/ci.yml/badge.svg)](https://github.com/Yasir-Khan-7/turnsafe/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/turnsafe.svg)](https://pypi.org/project/turnsafe/)
+[![Python](https://img.shields.io/pypi/pyversions/turnsafe.svg)](https://pypi.org/project/turnsafe/)
+[![Typed](https://img.shields.io/badge/typing-strict-blue.svg)](https://mypy.readthedocs.io/)
+[![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://github.com/Yasir-Khan-7/turnsafe/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Yasir-Khan-7/turnsafe/blob/main/LICENSE)
+
+</div>
+
+---
+
+## Did one of these errors bring you here?
+
+```text
+anthropic.BadRequestError: messages.4: `tool_use` ids were found without `tool_result` blocks
+immediately after: toolu_01A... Each `tool_use` block must have a corresponding `tool_result`
+block in the next message.
+```
+
+```text
+openai.BadRequestError: Invalid parameter: messages with role 'tool' must be a response to a
+preceeding message with 'tool_calls'.
+```
+
+```text
+openai.BadRequestError: An assistant message with 'tool_calls' must be followed by tool
+messages responding to each 'tool_call_id'. The following tool_call_ids did not have
+response messages: call_abc123
+```
+
+Each one means **a tool call got separated from its result**. Common causes:
+
+- You trimmed the history to fit the context window (`messages[-20:]`) and the cut landed in
+  the middle of a tool call.
+- You saved the conversation and reloaded it, and something got lost or reordered.
+- The agent crashed or was cancelled while a tool was running.
+- The user sent a message while tools were still running.
+
+After that, **every later request in the conversation fails** until someone fixes the history.
+
+`turnsafe` fixes the history before you send it. It works on the plain `messages` list you
+already pass to the OpenAI and Anthropic SDKs. It has no dependencies and needs no framework or
+network access.
+
+## Contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Try it without an API key](#try-it-without-an-api-key)
+- [How it works](#how-it-works)
+- [API](#api)
+- [Anthropic thinking blocks](#anthropic-thinking-blocks)
+- [How it compares](#how-it-compares)
+- [FAQ](#faq)
+- [Status and roadmap](#status-and-roadmap)
+- [Contributing](#contributing)
+
+## Install
+
+```bash
+pip install turnsafe
+```
+
+It needs Python 3.10 or newer and has zero runtime dependencies.
+
+## Quickstart
+
+Add one line before each API call in your agent loop:
+
+```python
+import anthropic
+import turnsafe
+
+client = anthropic.Anthropic()
+
+while True:
+    request = turnsafe.fit(turnsafe.repair(messages), max_tokens=150_000)
+    response = client.messages.create(
+        model="claude-sonnet-5", max_tokens=1024, tools=tools, messages=request
+    )
+    ...
+```
+
+- `repair()` heals a broken history.
+- `fit()` trims whole turns so the history fits your budget.
+
+They work the same way with `openai.OpenAI().chat.completions.create(...)`. The provider is
+detected from the message format, or you can pass `provider="openai"` or `"anthropic"`.
+
+For complete runnable agents that save and reload their history, see
+[`examples/anthropic_agent.py`](https://github.com/Yasir-Khan-7/turnsafe/blob/main/examples/anthropic_agent.py)
+and [`examples/openai_agent.py`](https://github.com/Yasir-Khan-7/turnsafe/blob/main/examples/openai_agent.py).
+
+## Try it without an API key
+
+```bash
+git clone https://github.com/Yasir-Khan-7/turnsafe && cd turnsafe
+pip install -e . && python examples/offline_demo.py
+```
+
+```text
+=== Anthropic: agent crashed between two parallel tool calls ===
+anthropic history has 1 error(s), 0 warning(s):
+  [error] messages[1] unanswered_tool_call: tool call 'toolu_2' has no tool result in the next user message
+  fix: messages[1] added_placeholder: no result for 'toolu_2'
+  after repair: anthropic history is valid.
+
+=== OpenAI: a user message landed between a call and its result ===
+openai history has 1 error(s), 0 warning(s):
+  [error] messages[3] misplaced_tool_result: result for tool call 'call_7' must be in the tool messages directly after the call
+  fix: messages[1] moved_result: moved result for 'call_7' from messages[3]
+  after repair: openai history is valid.
+
+=== fit() to 1,000 tokens ===
+kept 24 of 80 messages (~977 tokens), dropped 14 whole turns; valid: True
+```
+
+## How it works
+
+```text
+user ─┐
+      │  turn 1          fit() drops whole turns, oldest first.
+asst  │  (tool call) ─┐  A tool call and its results are always in the
+tool  │  (result)  ◄──┘  same turn, so they leave together or stay together.
+asst ─┘
+user ─┐
+      │  turn 2          repair() pairs every call with its result and fixes
+asst  │  (tool call) ─┐  anything the API would reject: missing results,
+user  │  "hurry!"     │  orphaned results, misplaced results, duplicates.
+tool  │  (result)  ◄──┘  ← misplaced: repair() moves it back next to its call
+asst ─┘
+```
+
+Every rule turnsafe checks comes from the provider's documentation, or from the exact API error
+text when the docs are silent. All sources are listed in
+[`docs/rules.md`](https://github.com/Yasir-Khan-7/turnsafe/blob/main/docs/rules.md).
+
+The core promises are checked by property-based tests that run thousands of randomly damaged
+histories on every change:
+
+- `repair()` output always passes `validate()`.
+- A valid history comes back unchanged.
+- `repair()` never mutates its input.
+- `fit()` never splits a tool call from its result.
+
+## API
+
+### `validate(messages, provider="auto") -> Report`
+
+`validate()` tells you what the API would reject, without changing anything.
+
+```python
+report = turnsafe.validate(messages)
+if not report:                  # falsy when there are errors
+    print(report.explain())
+report.raise_for_errors()       # or fail fast, for example in tests or CI
+```
+
+Each `Violation` has:
+- a stable `code`, such as `"orphan_tool_result"`
+- the message `index`
+- the `tool_call_id`
+- a `severity`, either `"error"` or `"warning"`
+
+### `repair(messages, provider="auto", *, on_missing="placeholder", placeholder=..., thinking="keep")`
+
+`repair()` returns a fixed copy of the history. Use `repair_detailed()` to also get a `Fix` for
+every change, which is useful for logging.
+
+```python
+messages, fixes = turnsafe.repair_detailed(messages)
+for fix in fixes:
+    log.warning("turnsafe: %s", fix)   # messages[1] added_placeholder: no result for 'toolu_2'
+```
+
+| Problem | What `repair()` does |
+|---|---|
+| A tool result whose call is gone, for example trimmed away | Drops it and keeps any other content in the same message. |
+| A tool call with no result, for example after an interrupted run | Adds an error result saying the tool didn't run. With `on_missing="strip"` it removes the call instead. |
+| A result in the wrong place, for example a user message got in between | Moves it back right after its call. |
+| A second result for the same call | Keeps the first. |
+| Anthropic: text before the `tool_result` blocks | Moves the results first. |
+| Anthropic: the same `tool_use` id used twice in the history | Renames the later call and its result. |
+| Anthropic: an empty user message, or a blank text block | Removes it. |
+
+`repair()` also guarantees:
+- It never mutates your list.
+- A valid history comes back unchanged.
+- The output passes `validate()`. The one exception is an Anthropic `system` message placed
+  first, which you have to move to the `system` parameter yourself.
+- By default it never rewrites an assistant message, so Anthropic thinking blocks and their
+  signatures survive.
+
+### `fit(messages, max_tokens, provider="auto", *, counter=approx_tokens, keep_system=True, keep_first_turn=False, thinking="keep")`
+
+`fit()` drops the oldest whole turns until the history fits in `max_tokens`.
+
+```python
+result = turnsafe.fit_detailed(messages, max_tokens=100_000, keep_first_turn=True)
+print(result.tokens, result.dropped_turns)
+```
+
+- `keep_system` keeps leading system and developer messages.
+- `keep_first_turn` keeps the first turn, which is usually the original task.
+- If even the latest turn doesn't fit, `fit()` raises `ContextBudgetError` instead of returning
+  a broken history.
+- If the input breaks the rules, it raises `InvalidHistoryError`, so call `repair()` first.
+- `max_tokens` covers the messages only. Leave room for tools, the system prompt and the reply.
+- The default counter is an offline estimate: about 4 characters per token, with images counted
+  by size rather than by their base64 length. Pass `counter=` for exact numbers, for example
+  with `tiktoken` or Anthropic's token-counting endpoint.
+
+### Rules checked
+
+| Code | Providers | Meaning |
+|---|---|---|
+| `unanswered_tool_call` | both | A tool call has no result |
+| `orphan_tool_result` | both | A result answers no call in the preceding assistant turn |
+| `misplaced_tool_result` | both | The result exists but isn't directly after its call |
+| `duplicate_tool_result` | both | A call has more than one result |
+| `duplicate_tool_call_id` | both | A tool call id is repeated. For Anthropic, this means anywhere in the history. |
+| `tool_result_not_first` | Anthropic | Text comes before the `tool_result` blocks in the user turn |
+| `system_in_messages` | Anthropic | An error when first. Elsewhere a warning, because only Opus 4.8+, Opus 5, Fable and Mythos accept it. |
+| `empty_content` | Anthropic | An empty user message, or a blank text block outside a `tool_result` |
+| `first_message_not_user` | Anthropic | Warning: Bedrock and some deployments require a user message first |
+
+The Anthropic API merges consecutive messages with the same role, and turnsafe does the same.
+Results split over several user messages in a row, or calls split over several assistant
+messages, are valid.
+
+## Anthropic thinking blocks
+
+By default, turnsafe never touches `thinking` or `redacted_thinking` blocks.
+
+**On Claude Fable 5.1 and Opus 5.5**, a replayed thinking block may be valid only while every
+message before it is unchanged. This is enforced by default for accounts created on or after
+2026-08-31. Trimming the front of the history then makes the API reject later thinking blocks
+with ``Invalid `signature` in `thinking` block``. There are two fixes:
+
+- Set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"` on the request. That's
+  the field the API error names, and the API then drops the stale blocks itself.
+- Or pass `thinking="strip_after_change"` to `fit()` and `repair()`. turnsafe then removes
+  thinking blocks after the first change, which is the documented recovery.
+
+Don't strip on other models. They expect the latest turn's thinking to be replayed. See the
+[details](https://github.com/Yasir-Khan-7/turnsafe/blob/main/docs/rules.md#anthropic-thinking-blocks).
+
+## How it compares
+
+| | turnsafe | litellm `modify_params` | LangChain `trim_messages` | pydantic-ai history repair |
+|---|---|---|---|---|
+| Works on plain SDK dicts, with no framework | ✅ | ❌ inside `litellm.completion()` | ❌ LangChain messages | ❌ pydantic-ai messages |
+| OpenAI **and** Anthropic formats | ✅ | Anthropic path only | ✅ | ✅ |
+| Reports problems without changing anything | ✅ `validate()` | ❌ | ❌ | ❌ |
+| Repairs broken pairs | ✅ | ✅ | ❌ | ✅ |
+| Trims to a token budget | ✅ | ❌ | ✅ | ❌ |
+| Trimming can't orphan a tool call | ✅ property-tested | – | ❌ [#33245](https://github.com/langchain-ai/langchain/issues/33245) | – |
+| Tells you what it changed | ✅ | ❌ | ❌ | ❌ |
+
+If your framework already handles this for you, keep using it. `turnsafe` is for agent loops
+written directly on the provider SDKs, for histories you store and reload yourself, and for
+anyone who wants to check a history before sending it. For how the problem was chosen and what
+we learned from existing tools, see
+[`docs/research.md`](https://github.com/Yasir-Khan-7/turnsafe/blob/main/docs/research.md).
+
+## FAQ
+
+**Does it call any API or send my data anywhere?**
+No. It's pure Python working on your list in memory.
+
+**Can I pass SDK objects instead of dicts?**
+Yes. Messages and content blocks that have `model_dump()` are accepted, for example
+`response.choices[0].message` or `response.content`. The output is always plain dicts.
+
+**What if a tool call id isn't a string?**
+turnsafe raises a `ValueError` naming the position, for example
+`messages[3].tool_calls[0].id must be a non-empty string`. A call without a usable id can't be
+matched to its result, so it isn't silently ignored.
+
+**What does the placeholder result say?**
+It says the tool call wasn't executed or its result was lost, and that the model shouldn't
+assume it succeeded. Change it with `placeholder="..."`.
+
+**My history ends with an assistant tool call because I'm about to run the tools. Is that
+an error?**
+`validate()` reports it, because the API would reject it if you sent it. Don't `repair()`
+a history while you're about to add the real results yourself.
+
+**Should I use this with server-side compaction?**
+Yes, they work together. Anthropic context editing and OpenAI Responses compaction make the
+context smaller, and turnsafe makes sure what you send is valid.
+
+## Status and roadmap
+
+- **v0.1:** OpenAI Chat Completions and Anthropic Messages.
+- **Planned:**
+  - OpenAI Responses API items
+  - Gemini `contents`
+  - an optional LangChain adapter
+- Legacy OpenAI `function_call` messages aren't checked.
+
+The version follows [Semantic Versioning](https://semver.org/). Violation codes and fix actions
+are public API. Changes are listed in the
+[CHANGELOG](https://github.com/Yasir-Khan-7/turnsafe/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome. See
+[CONTRIBUTING.md](https://github.com/Yasir-Khan-7/turnsafe/blob/main/CONTRIBUTING.md) to get
+set up. If you work with an AI coding agent, point it at
+[AGENT.md](https://github.com/Yasir-Khan-7/turnsafe/blob/main/AGENT.md). To report a security
+issue, see [SECURITY.md](https://github.com/Yasir-Khan-7/turnsafe/blob/main/SECURITY.md).
+
+Found a provider rule turnsafe gets wrong? Open an issue with the exact API error text. That's
+the most valuable report you can send.
+
+## License
+
+[MIT](https://github.com/Yasir-Khan-7/turnsafe/blob/main/LICENSE) © Yasir Khan