Messages and content¶
AssistantMessage¶
tau_llm.types.AssistantMessage
An assistant message from the LLM.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
api¶
tau_llm.types.AssistantMessage.api: str
No description. This object is marked but undocumented.
content¶
tau_llm.types.AssistantMessage.content: list[TextContent | ThinkingContent | ToolCall]
No description. This object is marked but undocumented.
error_message¶
tau_llm.types.AssistantMessage.error_message: str | None
No description. This object is marked but undocumented.
get_tool_calls¶
get_tool_calls() -> list[ToolCall]
tau_llm.types.AssistantMessage.get_tool_calls
Extract all tool calls from this message's content.
Returns
List of ToolCall objects found in content blocks.
model¶
tau_llm.types.AssistantMessage.model: str
No description. This object is marked but undocumented.
provider¶
tau_llm.types.AssistantMessage.provider: str
No description. This object is marked but undocumented.
response_id¶
tau_llm.types.AssistantMessage.response_id: str | None
No description. This object is marked but undocumented.
role¶
tau_llm.types.AssistantMessage.role: Literal['assistant']
No description. This object is marked but undocumented.
stop_reason¶
tau_llm.types.AssistantMessage.stop_reason: Literal['stop', 'length', 'toolUse', 'error', 'aborted']
No description. This object is marked but undocumented.
timestamp¶
tau_llm.types.AssistantMessage.timestamp: int
No description. This object is marked but undocumented.
usage¶
tau_llm.types.AssistantMessage.usage: Usage
No description. This object is marked but undocumented.
Attachment¶
class Attachment(token: str, start: int, end: int, kind: AttachmentKind, path: Path | None = None, size: int = 0, mime_type: str = '', note: str = '')
tau_agent_core.attachments.Attachment
One @file reference found in a prompt, and what will become of it.
Frozen, and carrying its own span, because a frontend uses it for two things
at once: drawing a row that says what is attached, and editing the text that
produced it when the human removes that row (:func:remove_attachment).
Constructor parameters
token: str— The reference as typed, without the@. Relative paths stay relative — this is what thefilenameattribute of the emitted block says, so the model sees the name the human used.start: int— Index of the@in the text this was scanned from.end: int— Index one past the last character of the reference.text[start:end]is"@" + token, which :func:remove_attachmentchecks before it cuts.kind: AttachmentKind— What will be sent. See :data:AttachmentKind.path: Path | None = None— The resolved absolute path, orNonewhenkindis"unresolved".size: int = 0— Size on disk in bytes. 0 when unresolved.mime_type: str = ''— The image mime type;""for everything else.note: str = ''— Why this is a"reference"rather than inline, or why it is unresolved.""when there is nothing to explain. It is shown to the human AND written into the block, because a model told only "the content is missing" cannot tell a 4 MB file from an unreadable one.
AttachmentCompletions¶
class AttachmentCompletions(start: int, end: int, token: str, matches: tuple[PathCompletion, ...], total: int)
tau_agent_core.attachments.AttachmentCompletions
The candidate paths for the @… the cursor is inside.
The same shape as :class:~tau_agent_core.commands.CommandCompletions, and
for the same reason: an empty matches is not "nothing to say", it is the
warning that this @… names no file and will be sent as ordinary text.
Constructor parameters
start: int— Index of the@in the text.end: int— Index one past the token, i.e. the end of the span a completion replaces. The whole token is replaced even when the cursor sits in the middle of it — one rule, so what Tab does is predictable.token: str— The reference as typed so far, without the@.matches: tuple[PathCompletion, ...]— The candidates, alphabetical, at most :data:_COMPLETION_LIMIT.total: int— How many candidates matched before that cap, so a frontend can say that the list is not all of them.
ImageContent¶
tau_llm.types.ImageContent
An image content block in a message.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
data¶
tau_llm.types.ImageContent.data: str
No description. This object is marked but undocumented.
mime_type¶
tau_llm.types.ImageContent.mime_type: str
No description. This object is marked but undocumented.
type¶
tau_llm.types.ImageContent.type: Literal['image']
No description. This object is marked but undocumented.
Model¶
tau_llm.types.Model
LLM model configuration.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
Represents a model with its provider and connection details. Serializes to OpenAI-compatible dict format.
api¶
tau_llm.types.Model.api: str
No description. This object is marked but undocumented.
base_url¶
tau_llm.types.Model.base_url: str
No description. This object is marked but undocumented.
compat¶
tau_llm.types.Model.compat: Compat | None
No description. This object is marked but undocumented.
context_window¶
tau_llm.types.Model.context_window: int
No description. This object is marked but undocumented.
extra_body¶
tau_llm.types.Model.extra_body: dict[str, Any]
No description. This object is marked but undocumented.
grammar_dialect¶
tau_llm.types.Model.grammar_dialect: Literal['llguidance', 'gbnf'] | None
No description. This object is marked but undocumented.
id¶
tau_llm.types.Model.id: str
No description. This object is marked but undocumented.
max_tokens¶
tau_llm.types.Model.max_tokens: int
No description. This object is marked but undocumented.
name¶
tau_llm.types.Model.name: str
No description. This object is marked but undocumented.
provider¶
tau_llm.types.Model.provider: str
No description. This object is marked but undocumented.
reasoning¶
tau_llm.types.Model.reasoning: bool
No description. This object is marked but undocumented.
reasoning_replay¶
tau_llm.types.Model.reasoning_replay: Literal['all', 'turn', 'off']
No description. This object is marked but undocumented.
request_timeout¶
tau_llm.types.Model.request_timeout: float | None
No description. This object is marked but undocumented.
requires_tool_call_id¶
tau_llm.types.Model.requires_tool_call_id: bool
No description. This object is marked but undocumented.
server_features¶
tau_llm.types.Model.server_features: list[str]
No description. This object is marked but undocumented.
stream¶
tau_llm.types.Model.stream: bool
No description. This object is marked but undocumented.
strict_reasoning_formats¶
tau_llm.types.Model.strict_reasoning_formats: bool
No description. This object is marked but undocumented.
supports_multimodal_function_response¶
tau_llm.types.Model.supports_multimodal_function_response: bool
No description. This object is marked but undocumented.
temperature¶
tau_llm.types.Model.temperature: float | None
No description. This object is marked but undocumented.
thinking_level_map¶
tau_llm.types.Model.thinking_level_map: dict[str, str | dict[str, Any] | None] | None
No description. This object is marked but undocumented.
to_openai_format¶
to_openai_format() -> dict[str, Any]
tau_llm.types.Model.to_openai_format
Serialize to OpenAI-compatible format.
Returns
dict with keys compatible with OpenAI API: - id: model identifier - name: human-readable name - provider: provider name - base_url: API endpoint - max_completion_tokens: max tokens for completion
PathCompletion¶
class PathCompletion(name: str, detail: str, is_dir: bool)
tau_agent_core.attachments.PathCompletion
One candidate path for a half-typed @….
Constructor parameters
name: str— What replaces the token after the@— the whole path as it would be typed, not just the last segment, so inserting it is a single span replacement. Directories end in/.detail: str— A short right-hand column for the popup: a human size for a file,"dir"for a directory.is_dir: bool— Whether this candidate is a directory. A directory is inserted without a trailing space, because the next thing the human wants is to keep completing into it.
RenderedAttachments¶
class RenderedAttachments(prefix: str, images: tuple[dict[str, Any], ...], failures: tuple[str, ...])
tau_agent_core.attachments.RenderedAttachments
The prompt prefix and image blocks a set of attachments produced.
Constructor parameters
prefix: str— The<attachment>/<reference>blocks, in the order the references appeared, each ending in a newline. Prepended to the user's own text — the human's words stay last, where the model reads them as the instruction rather than as a caption on the final file.images: tuple[dict[str, Any], ...]—ImageContent-shaped block dicts ({"type": "image", "data": <base64>, "mime_type": …}) to put onSubmission.images.failures: tuple[str, ...]— One human-readable line per attachment that could not be sent as intended. Empty when everything worked. The frontend shows these; the corresponding block already says the same thing to the model.
TextContent¶
tau_llm.types.TextContent
A text content block in a message.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
text¶
tau_llm.types.TextContent.text: str
No description. This object is marked but undocumented.
type¶
tau_llm.types.TextContent.type: Literal['text']
No description. This object is marked but undocumented.
ThinkingContent¶
tau_llm.types.ThinkingContent
A thinking/reasoning content block.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
cached_tokens¶
tau_llm.types.ThinkingContent.cached_tokens: int
No description. This object is marked but undocumented.
thinking¶
tau_llm.types.ThinkingContent.thinking: str
No description. This object is marked but undocumented.
thinking_signature¶
tau_llm.types.ThinkingContent.thinking_signature: str | dict[str, Any]
No description. This object is marked but undocumented.
type¶
tau_llm.types.ThinkingContent.type: Literal['thinking']
No description. This object is marked but undocumented.
ToolCall¶
tau_llm.types.ToolCall
A tool call content block in a message.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
arguments¶
tau_llm.types.ToolCall.arguments: dict[str, Any]
No description. This object is marked but undocumented.
id¶
tau_llm.types.ToolCall.id: str
No description. This object is marked but undocumented.
name¶
tau_llm.types.ToolCall.name: str
No description. This object is marked but undocumented.
provider_signature¶
tau_llm.types.ToolCall.provider_signature: dict[str, Any]
No description. This object is marked but undocumented.
type¶
tau_llm.types.ToolCall.type: Literal['toolCall']
No description. This object is marked but undocumented.
ToolResultMessage¶
tau_llm.types.ToolResultMessage
A tool result message.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
content¶
tau_llm.types.ToolResultMessage.content: list[TextContent | ImageContent]
No description. This object is marked but undocumented.
details¶
tau_llm.types.ToolResultMessage.details: dict[str, Any] | None
No description. This object is marked but undocumented.
is_error¶
tau_llm.types.ToolResultMessage.is_error: bool
No description. This object is marked but undocumented.
role¶
tau_llm.types.ToolResultMessage.role: Literal['toolResult']
No description. This object is marked but undocumented.
timestamp¶
tau_llm.types.ToolResultMessage.timestamp: int
No description. This object is marked but undocumented.
tool_call_id¶
tau_llm.types.ToolResultMessage.tool_call_id: str
No description. This object is marked but undocumented.
tool_name¶
tau_llm.types.ToolResultMessage.tool_name: str
No description. This object is marked but undocumented.
Usage¶
tau_llm.types.Usage
Token usage information for an LLM response.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
Usage is immutable (frozen) — once created, its fields cannot be modified.
cache_read_tokens¶
tau_llm.types.Usage.cache_read_tokens: int
No description. This object is marked but undocumented.
cache_write_tokens¶
tau_llm.types.Usage.cache_write_tokens: int
No description. This object is marked but undocumented.
cost¶
tau_llm.types.Usage.cost: dict[str, float]
No description. This object is marked but undocumented.
extra¶
tau_llm.types.Usage.extra: dict[str, Any]
No description. This object is marked but undocumented.
input_tokens¶
tau_llm.types.Usage.input_tokens: int
No description. This object is marked but undocumented.
model_config¶
tau_llm.types.Usage.model_config
No description. This object is marked but undocumented.
output_tokens¶
tau_llm.types.Usage.output_tokens: int
No description. This object is marked but undocumented.
total_tokens¶
tau_llm.types.Usage.total_tokens: int
No description. This object is marked but undocumented.
UserMessage¶
tau_llm.types.UserMessage
A user message.
Reference: SUBPHASE-0.0.md, "1. Messages" section.
content¶
tau_llm.types.UserMessage.content: str | list[TextContent | ImageContent]
No description. This object is marked but undocumented.
role¶
tau_llm.types.UserMessage.role: Literal['user']
No description. This object is marked but undocumented.
timestamp¶
tau_llm.types.UserMessage.timestamp: int
No description. This object is marked but undocumented.
clamp_thinking_level¶
clamp_thinking_level(model: Model, level: ModelThinkingLevel) -> ModelThinkingLevel
tau_llm.models.clamp_thinking_level
Clamp level to the nearest level model actually supports.
If the exact level is supported it is returned unchanged. Otherwise search
upward (more effort) first, then downward, falling back to the lowest
supported level ("off" for a non-reasoning model). Mirrors pi
clampThinkingLevel (models.ts:64-83).
Parameters
model: Model— (no description)level: ModelThinkingLevel— (no description)
complete_attachment¶
complete_attachment(text: str, cursor: int, *, cwd: Path | None = None) -> AttachmentCompletions | None
tau_agent_core.attachments.complete_attachment
Candidate paths for the @… the cursor is inside. None for "not one".
Pure in the same sense as :func:~tau_agent_core.commands.complete_command:
it reads the filesystem but decides nothing and runs nothing, so an editor, a
test and another frontend all get the same list.
Matching is a case-sensitive prefix test on the last path segment, which is
what a shell does. Hidden entries are offered only once the prefix itself
starts with a dot, so @ in a home directory does not open with forty
dotfiles.
Parameters
text: str— The editor's contents.cursor: int— The cursor's character offset intotext.cwd: Path | None = None— The directory relative references resolve against. Defaults to the process working directory.
Returns
class:AttachmentCompletions when the cursor is inside a @…, with an empty matches when nothing matches — that emptiness is the "this names no file" warning, not an absence of information. None when the cursor is not inside a reference at all.
elide_attachment_bodies¶
elide_attachment_bodies(text: str) -> str
tau_agent_core.attachments.elide_attachment_bodies
Replace inlined attachment bodies with a one-line summary, for display.
A transcript is a conversation, and a 10 KB file pasted into a user bubble pushes the conversation off the screen. This is the DISPLAY transform for that: the block keeps its header and its shape, and its body becomes a visible marker saying how much was elided.
It is deliberately not a lossy record. What was sent is on the wire and in the session log, unchanged; this is what the frontend draws. The marker says so, rather than leaving a shortened body that reads as the whole file.
Parameters
text: str— A prompt that may contain<attachment>blocks.
Returns
The same text with each inlined body replaced by a summary line. Empty (image) attachment blocks are self-closing and are untouched.
get_supported_thinking_levels¶
get_supported_thinking_levels(model: Model) -> list[ModelThinkingLevel]
tau_llm.models.get_supported_thinking_levels
Return the levels model supports, least → most effort.
A non-reasoning model supports only ["off"]. Otherwise every level is
supported except those the thinking_level_map explicitly nulls out, with
one special case: "xhigh" is available only when the map provides an
entry for it (it is a non-standard extension). Mirrors pi
getSupportedThinkingLevels (models.ts:53-63).
Parameters
model: Model— (no description)
is_valid_thinking_level¶
is_valid_thinking_level(level: str) -> bool
tau_llm.models.is_valid_thinking_level
True if level is one of the known levels ("off".."xhigh").
Parameters
level: str— (no description)
remove_attachment¶
remove_attachment(text: str, attachment: Attachment) -> str
tau_agent_core.attachments.remove_attachment
Delete one @file reference from text.
What "remove this attachment" means for a reference typed into a prompt: the
@… word goes away, because the word IS the attachment. The separator it
leaves behind is collapsed, so removing the middle of look at @a.py and
@b.py does not leave a double space.
Parameters
text: str— The text the attachment was scanned from.attachment: Attachment— The reference to remove.
Returns
text without the reference.
Raises
ValueError—textno longer holds that reference at that span. The caller's text has changed since the scan, and cutting the recorded span would delete something else (Fail-Early).
render_attachments¶
render_attachments(attachments: Sequence[Attachment], *, max_image_dimension: int = DEFAULT_MAX_IMAGE_DIMENSION) -> RenderedAttachments
tau_agent_core.attachments.render_attachments
Build the prompt prefix and the image blocks for attachments.
Reads each file again — :func:scan_attachments deliberately keeps no
content — so what goes to the model is the file as it stands now, and a file
that has been deleted or chmod-ed since the human typed the @ is reported
rather than sent as stale bytes.
Images are bounded by :func:~tau_agent_core.tools.image_resize.resize_image
before they are encoded. Pillow missing is NOT a reason to send the image
unresized (see that module): the attachment degrades to a <reference>
naming the extra to install, and the frontend is told through failures.
This is CPU-bound for a large image, because bounding one decodes it.
Parameters
attachments: Sequence[Attachment]— What :func:scan_attachmentsreturned."unresolved"entries are skipped — they are prose, and the human's own text already contains them.max_image_dimension: int = DEFAULT_MAX_IMAGE_DIMENSION— The largest width or height, in pixels, an attached image may have. Larger images are scaled down.
Returns
class:RenderedAttachments.
scan_attachments¶
scan_attachments(text: str, *, cwd: Path | None = None, inline_limit: int = DEFAULT_INLINE_LIMIT) -> tuple[Attachment, ...]
tau_agent_core.attachments.scan_attachments
Find the @file references in text and say what each one is.
Cheap enough to call on every keystroke, which is what the chat editor does:
it stats every reference and reads only the files that are within
inline_limit, because deciding "text or binary" has no answer that does
not look at the bytes. It reads nothing over the limit and returns no file
contents — :func:render_attachments reads again at submit time, so what is
sent is the file as it stood when the human pressed Enter.
A reference that names nothing is returned with kind="unresolved" rather
than dropped, so a caller that wants to say so can. Nothing here raises: an
unreadable file is a "reference" carrying the reason.
Parameters
text: str— The prompt as typed.cwd: Path | None = None— The directory relative references resolve against. Defaults to the process working directory.inline_limit: int = DEFAULT_INLINE_LIMIT— The largest file, in bytes, whose content is pasted into the prompt. Larger files become<reference>blocks.
Returns
class:Attachment per reference, in the order they appear in text.