- tools.md: drop the stray article in "every tool is a defined as" and the doubled word in "Toolbox classes can be be configured".
- contributing.md: fix the doubled "an an" in the example prompt (both the streaming and --no-stream snippets).
The description of the `register_fragment_loaders` hook incorrectly
referred to `register_template_loaders` as the hook to use. These are
two distinct hooks; fragment loader plugins must use
`register_fragment_loaders`.
Also fixed a typo: "de-duplicatino" → "de-duplication".
AI-assisted contribution.
* PauseChain primitive + chain resume from pending tool calls
Two features that together give chains a first-class suspend/resume
story for human-in-the-loop tools:
llm.PauseChain: raise inside a tool implementation to stop the chain
cleanly. Unlike other exceptions it is not converted into an error
ToolResult - it propagates to the caller with .tool_call (the paused
call) and .tool_results (completed sibling results) attached, and no
provider call is made with a placeholder result. Failure semantics
for concurrent tool execution are now defined: async sibling tasks
always run to completion before a pause or hook exception propagates
(gather with return_exceptions, raised after collection), so nothing
is orphaned mid-flight; sync execution stops at the paused call,
leaving later calls unstarted so they can safely run on resume.
Chain resume: chain(messages=history, tools=...) now detects a
history ending in an assistant message with unresolved tool calls -
e.g. one persisted when a previous run paused or crashed - executes
those calls through the normal before_call/after_call machinery
(skipping any that already have results), then sends the results to
the model as a standard tool-result turn. A resumed call may pause
again, enabling multi-question flows. Histories where a user or
assistant message follows the calls are left alone. Also adds
execute_tool_calls(tool_calls_list=) for executing an explicit list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Guarantee every tool call has a unique tool_call_id
add_tool_call() now synthesizes a unique tc_-prefixed id (monotonic
ULID) whenever the provider did not supply one. Previously consumers
correlating tool calls with results - or keying external state on a
specific invocation - had to invent fallback matching schemes for
id-less providers, and test models like llm-echo exercised different
code paths than production providers.
Provider-supplied ids are preserved untouched, and responses
rehydrated from the logs database keep their stored ids (synthesis
only happens at add_tool_call time). Existing tests that asserted
tool_call_id None now normalize or mask the synthesized ids.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Tool implementations can receive the ToolCall via llm_tool_call parameter
Tool functions (sync or async, including Toolbox methods) that declare
a parameter named llm_tool_call are now passed the llm.ToolCall object
for the current invocation. The parameter is reserved: it is excluded
from the input schema exposed to the model and is only injected when
declared explicitly - a **kwargs catch-all does not receive it.
This lets tool implementations key external state against the unique
tool_call_id, e.g. for human-in-the-loop approval flows that need to
resume a specific tool call after the answer arrives.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Ran Black
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Accepts model options as an explicit dict alongside the existing
**kwargs form. The kwargs form continues to work unchanged for
backwards compatibility but is no longer documented. Mixing the two
forms with overlapping keys raises TypeError.
Applies to Model.prompt, Conversation.prompt, Response.reply and
their async equivalents. .chain() already used this pattern.
Co-authored-by: Claude <noreply@anthropic.com>
Adds a `reasoning` column to the responses table (migration m022)
populated from concatenated visible-reasoning text in the assembled
message. `llm logs --md` renders it under a `## Reasoning` heading
above the response when present.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sync: response.messages() forces execution if not drained, so callers
no longer have to remember to call .text() first. Async: `await
response.messages()` awaits the force.
Internal sync paths (_response_to_dict, _chain_for_tool_results,
_build_full_chain, Response.reply, AsyncResponse.reply) use a new
private _messages_now() helper that assumes the response is already
drained, so they don't have to await on async responses.
Drops the now-obsolete "accessing .messages on un-awaited
AsyncResponse raises" parity test — that constraint goes away with
the method form.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Zero-arg sugar: when a response made tool calls and tool_results= is
not passed, reply() runs self.execute_tool_calls() and threads the
results into the next turn. Pass tool_results= explicitly to skip
the auto-execute path (e.g. for mutated or synthetic results). Also
forwards self.prompt.tools to the next turn so the model can call
the same tools again, mirroring Conversation.prompt's tools-or-self
rule.
AsyncResponse.reply() is now an awaitable coroutine — `await
response.reply(...)` — so the auto-execute path can `await
self.execute_tool_calls()` internally. This is a non-shipped API
break: existing async-reply callers in the test suite updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Substantially expanded docs/plugins/advanced-model-plugins.md with
the plugin-author guide to the new machinery. Distilled from the
actual llm-anthropic and llm-gemini implementations so plugin
authors have a recipe that mirrors what real providers do.
New / updated sections (doc grew 317 → 663 lines):
- "Attachments from previous conversations" trimmed to a pointer at
prompt.messages — the old pattern of walking conversation.responses
is replaced by the canonical chain view.
- "Structured messages and streaming events"
- StreamEvent contract, backward compat for plain-str plugins
- Full field reference (type / chunk / part_index / tool_call_id /
provider_metadata / server_executed / tool_name)
- part_index allocation rules with two worked examples:
block-keyed (Anthropic-style content_block_start events) and
kind-tracking (Gemini-style chunk-per-part)
- Reasoning: streamed text + opaque _reasoning_token_count, with
the OpenAI-specific gotcha about reading reasoning_tokens BEFORE
set_usage mutates the dict
- Tool calls — tool_call_name + tool_call_args pattern, reminder
that response.add_tool_call() is separately required for
chain-execution
- Server-side tools — server_executed=True on events, raw payload
in provider_metadata for round-trip, post-stream emission for
providers that don't stream tool-result contents
- Opaque provider_metadata — Anthropic signature, Gemini
thoughtSignature, OpenAI encrypted_content — with namespacing
guidance
- Non-streaming path — one event per content block
- "Consuming prompt.messages in build_messages"
- The invariant: prompt.messages is always the full chain; don't
walk conversation.responses (would double-emit)
- Worked build_messages example that dispatches per Part subtype
- Role mapping across OpenAI / Anthropic / Gemini conventions
- Role-alternation merging
- "Restoring opaque metadata on subsequent requests"
- How to read provider_metadata off prior-turn Parts and fold the
signatures back into the outgoing request body
670 tests still green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lock in the "application does its own persistence without SQLite"
story with:
- Five integration tests covering: Message.to_dict / from_dict
round-trip, re-inflating messages and continuing a conversation,
tool calls + results round-trip, redacted reasoning Parts
round-trip, and provider_metadata round-trip.
- A new "Structured messages and streaming events" section in
docs/python-api.md walking users through messages=[...],
stream_events(), response.messages, and the JSON round-trip
pattern.
No new code — the machinery landed in Phases 1-3. This phase is
validation + documentation.
580 tests passing overall.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Simon Willison