`pi_llm.types`¶

`types` ¶

Core type definitions for pi_llm.

Pydantic models, type aliases, streaming events, and configuration dataclasses used throughout the pi_llm library.

`StopReason = Literal['stop', 'length', 'toolUse', 'error', 'aborted']` `module-attribute` ¶

Why an LLM response ended.

`ThinkingLevel = Literal['minimal', 'low', 'medium', 'high', 'xhigh']` `module-attribute` ¶

Extended thinking / reasoning effort level.

Note: "off" is only available in the agent layer (see AgentThinkingLevel).

`CacheRetention = Literal['none', 'short', 'long']` `module-attribute` ¶

Prompt cache retention preference.

`UserContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')]` `module-attribute` ¶

Content block within a user message (text or image).

`AssistantContentItem = Annotated[TextContent | ThinkingContent | ToolCall, Field(discriminator='type')]` `module-attribute` ¶

Content block within an assistant message (text, thinking, or tool call).

`ToolResultContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')]` `module-attribute` ¶

Content block within a tool result message (text or image).

`Message = Annotated[UserMessage | AssistantMessage | ToolResultMessage, Field(discriminator='role')]` `module-attribute` ¶

Discriminated union of all message types (user, assistant, toolResult).

`AssistantMessageEvent = StartEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | DoneEvent | ErrorEvent` `module-attribute` ¶

Union of all streaming event types.

`BaseModelWithAliases` ¶

Bases: BaseModel

Base for all Pydantic models. Accepts both snake_case and camelCase.

`CostBreakdown` ¶

Bases: BaseModelWithAliases

Dollar cost breakdown for a single LLM request.

Attributes:

Name	Type	Description
`input`	`float`	Cost for input tokens.
`output`	`float`	Cost for output tokens.
`cache_read`	`float`	Cost for tokens read from prompt cache.
`cache_write`	`float`	Cost for tokens written to prompt cache.
`total`	`float`	Sum of all cost components.

`Usage` ¶

Bases: BaseModelWithAliases

Token usage for a single LLM request.

Attributes:

Name	Type	Description
`input`	`int`	Number of input tokens.
`output`	`int`	Number of output tokens.
`cache_read`	`int`	Tokens read from prompt cache.
`cache_write`	`int`	Tokens written to prompt cache.
`total_tokens`	`int`	Sum of all token counts.
`cost`	`CostBreakdown`	Dollar cost breakdown (populated by `calculate_cost`).

`ModelCost` ¶

Bases: BaseModelWithAliases

Cost per million tokens for a model.

Attributes:

Name	Type	Description
`input`	`float`	Cost per 1M input tokens.
`output`	`float`	Cost per 1M output tokens.
`cache_read`	`float`	Cost per 1M cached-read tokens.
`cache_write`	`float`	Cost per 1M cached-write tokens.

`TextContent` ¶

Bases: BaseModelWithAliases

A block of text content within a message.

Attributes:

Name	Type	Description
`type`	`Literal['text']`	Always `"text"`.
`text`	`str`	The text content.
`text_signature`	`str \| None`	Opaque signature for cross-provider handoff.

`ThinkingContent` ¶

Bases: BaseModelWithAliases

A block of model reasoning / "thinking" content.

Attributes:

Name	Type	Description
`type`	`Literal['thinking']`	Always `"thinking"`.
`thinking`	`str`	The reasoning text.
`thinking_signature`	`str \| None`	Opaque signature for cross-provider handoff.
`redacted`	`bool \| None`	Whether the content was redacted by the provider.

`ImageContent` ¶

Bases: BaseModelWithAliases

A base64-encoded image within a message.

Attributes:

Name	Type	Description
`type`	`Literal['image']`	Always `"image"`.
`data`	`str`	Base64-encoded image data.
`mime_type`	`str`	MIME type (e.g. `"image/jpeg"`).

`ToolCall` ¶

Bases: BaseModelWithAliases

An LLM request to invoke a tool.

Attributes:

Name	Type	Description
`type`	`Literal['toolCall']`	Always `"toolCall"`.
`id`	`str`	Unique identifier for this tool call.
`name`	`str`	Name of the tool to invoke.
`arguments`	`dict[str, Any]`	Parsed arguments matching the tool's JSON Schema.
`thought_signature`	`str \| None`	Opaque signature for reasoning context.

`UserMessage` ¶

Bases: BaseModelWithAliases

A message from the user.

Attributes:

Name	Type	Description
`role`	`Literal['user']`	Always `"user"`.
`content`	`str \| list[UserContentItem]`	Plain text string or a list of content blocks.
`timestamp`	`int`	Unix timestamp in milliseconds.

`AssistantMessage` ¶

Bases: BaseModelWithAliases

A response from the LLM assistant.

All fields have defaults to support incremental construction during streaming. The message is progressively built up as events arrive.

Attributes:

Name	Type	Description
`role`	`Literal['assistant']`	Always `"assistant"`.
`content`	`list[AssistantContentItem]`	List of content blocks (text, thinking, tool calls).
`api`	`str`	API identifier (e.g. `"openai-responses"`).
`provider`	`str`	Provider name (e.g. `"openai"`).
`model`	`str`	Model identifier used for this response.
`response_id`	`str \| None`	Provider-assigned response ID.
`usage`	`Usage`	Token usage and cost breakdown.
`stop_reason`	`StopReason`	Why the response ended.
`error_message`	`str \| None`	Error description if `stop_reason` is `"error"`.
`timestamp`	`int`	Unix timestamp in milliseconds.

`ToolResultMessage` ¶

Bases: BaseModelWithAliases

The result of executing a tool, sent back to the LLM.

Attributes:

Name	Type	Description
`role`	`Literal['toolResult']`	Always `"toolResult"`.
`tool_call_id`	`str`	ID of the `ToolCall` this result responds to.
`tool_name`	`str`	Name of the tool that was executed.
`content`	`list[ToolResultContentItem]`	Result content blocks (text or images).
`details`	`Any \| None`	Arbitrary metadata about the execution.
`is_error`	`bool`	Whether the tool execution failed.
`timestamp`	`int`	Unix timestamp in milliseconds.

`Tool` ¶

Bases: BaseModelWithAliases

A tool definition that can be passed to an LLM.

Tools enable LLMs to interact with external systems by defining a name, description, and JSON Schema for parameters.

Attributes:

Name	Type	Description
`name`	`str`	Unique identifier for the tool.
`description`	`str`	Human-readable description the LLM uses to decide when to call this tool.
`parameters`	`dict[str, Any]`	JSON Schema object describing the tool's parameters.

`from_pydantic(name, description, model_class)` `classmethod` ¶

Create a Tool from a Pydantic model class.

The model's JSON schema is used as the tool's parameter schema.

Parameters:

Name	Type	Description	Default
`name`	`str`	Tool name.	required
`description`	`str`	Tool description for the LLM.	required
`model_class`	`type[BaseModel]`	Pydantic model whose schema defines the parameters.	required

Returns:

Type	Description
`Tool`	A new Tool instance.

`Model` ¶

Bases: BaseModelWithAliases

An LLM model descriptor.

Constructed via get_model() or fetch_models(). Contains all metadata needed to make API calls: endpoint, pricing, capabilities.

Attributes:

Name	Type	Description
`id`	`str`	Model identifier (e.g. `"gpt-4o"`).
`name`	`str`	Display name.
`api`	`str`	API backend identifier (e.g. `"openai-responses"`).
`provider`	`str`	Provider name (e.g. `"openai"`).
`base_url`	`str`	API base URL.
`reasoning`	`bool`	Whether the model supports extended thinking.
`input_types`	`list[str]`	Supported input modalities (e.g. `["text", "image"]`).
`cost`	`ModelCost \| None`	Pricing per million tokens, or `None` if unknown.
`context_window`	`int`	Maximum context window size in tokens.
`max_tokens`	`int`	Maximum output tokens per request.
`headers`	`dict[str, str] \| None`	Custom HTTP headers to include in API requests.

`Context` ¶

Bases: BaseModelWithAliases

Conversation context passed to the LLM.

A serializable snapshot of the current conversation state including system instructions, message history, and available tools.

Attributes:

Name	Type	Description
`system_prompt`	`str`	System-level instructions for the LLM.
`messages`	`list[Message]`	Conversation history.
`tools`	`list[Tool]`	Tools available to the LLM.

`StreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None)` `dataclass` ¶

Options for provider-level streaming calls.

Attributes:

Name	Type	Description
`temperature`	`float \| None`	Sampling temperature (`None` for provider default).
`max_tokens`	`int \| None`	Maximum output tokens.
`api_key`	`str \| None`	API key override (falls back to environment variable).
`cancel_event`	`Event \| None`	Event to signal request cancellation.
`cache_retention`	`CacheRetention \| None`	Prompt caching preference.
`session_id`	`str \| None`	Session ID for prompt caching.
`on_payload`	`Callable[[Any, Model], Any] \| None`	Hook called with raw API params before the request.
`headers`	`dict[str, str] \| None`	Additional HTTP headers.
`max_retry_delay_ms`	`int \| None`	Cap on retry backoff in milliseconds.
`metadata`	`dict[str, Any] \| None`	Arbitrary metadata passed to the provider.

`SimpleStreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None, reasoning=None, thinking_budgets=None)` `dataclass` ¶

Bases: StreamOptions

Options for the simplified streaming API (stream_simple / complete_simple).

Extends StreamOptions with reasoning support.

Attributes:

Name	Type	Description
`reasoning`	`ThinkingLevel \| None`	Extended thinking level (`None` to disable).
`thinking_budgets`	`dict[str, int] \| None`	Custom token budgets per thinking level.

`StartEvent(partial)` `dataclass` ¶

Emitted when streaming begins.

`TextStartEvent(content_index, partial)` `dataclass` ¶

Emitted when a new text content block begins streaming.

`TextDeltaEvent(content_index, delta, partial)` `dataclass` ¶

Emitted for each incremental chunk of text content.

`TextEndEvent(content_index, content, partial)` `dataclass` ¶

Emitted when a text content block finishes streaming.

`ThinkingStartEvent(content_index, partial)` `dataclass` ¶

Emitted when a thinking/reasoning block begins streaming.

`ThinkingDeltaEvent(content_index, delta, partial)` `dataclass` ¶

Emitted for each incremental chunk of thinking content.

`ThinkingEndEvent(content_index, content, partial)` `dataclass` ¶

Emitted when a thinking/reasoning block finishes streaming.

`ToolCallStartEvent(content_index, partial)` `dataclass` ¶

Emitted when a tool call begins streaming.

`ToolCallDeltaEvent(content_index, delta, partial)` `dataclass` ¶

Emitted for each incremental chunk of tool call arguments.

`ToolCallEndEvent(content_index, tool_call, partial)` `dataclass` ¶

Emitted when a tool call finishes streaming and arguments are complete.

`DoneEvent(reason, message)` `dataclass` ¶

Emitted when streaming completes successfully.

`ErrorEvent(reason, error)` `dataclass` ¶

Emitted when streaming ends due to an error or cancellation.

pi_llm.types¶

types ¶

StopReason = Literal['stop', 'length', 'toolUse', 'error', 'aborted'] module-attribute ¶

ThinkingLevel = Literal['minimal', 'low', 'medium', 'high', 'xhigh'] module-attribute ¶

CacheRetention = Literal['none', 'short', 'long'] module-attribute ¶

UserContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')] module-attribute ¶

AssistantContentItem = Annotated[TextContent | ThinkingContent | ToolCall, Field(discriminator='type')] module-attribute ¶

ToolResultContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')] module-attribute ¶

Message = Annotated[UserMessage | AssistantMessage | ToolResultMessage, Field(discriminator='role')] module-attribute ¶

AssistantMessageEvent = StartEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | DoneEvent | ErrorEvent module-attribute ¶

BaseModelWithAliases ¶

CostBreakdown ¶

Usage ¶

ModelCost ¶

TextContent ¶

ThinkingContent ¶

ImageContent ¶

ToolCall ¶

UserMessage ¶

AssistantMessage ¶

ToolResultMessage ¶

Tool ¶

from_pydantic(name, description, model_class) classmethod ¶

Model ¶

Context ¶

StreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None) dataclass ¶

SimpleStreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None, reasoning=None, thinking_budgets=None) dataclass ¶

StartEvent(partial) dataclass ¶

TextStartEvent(content_index, partial) dataclass ¶

TextDeltaEvent(content_index, delta, partial) dataclass ¶

TextEndEvent(content_index, content, partial) dataclass ¶

ThinkingStartEvent(content_index, partial) dataclass ¶

ThinkingDeltaEvent(content_index, delta, partial) dataclass ¶

ThinkingEndEvent(content_index, content, partial) dataclass ¶

ToolCallStartEvent(content_index, partial) dataclass ¶

ToolCallDeltaEvent(content_index, delta, partial) dataclass ¶

ToolCallEndEvent(content_index, tool_call, partial) dataclass ¶

DoneEvent(reason, message) dataclass ¶

ErrorEvent(reason, error) dataclass ¶

`pi_llm.types`¶

`types` ¶

`StopReason = Literal['stop', 'length', 'toolUse', 'error', 'aborted']` `module-attribute` ¶

`ThinkingLevel = Literal['minimal', 'low', 'medium', 'high', 'xhigh']` `module-attribute` ¶

`CacheRetention = Literal['none', 'short', 'long']` `module-attribute` ¶

`UserContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')]` `module-attribute` ¶

`AssistantContentItem = Annotated[TextContent | ThinkingContent | ToolCall, Field(discriminator='type')]` `module-attribute` ¶

`ToolResultContentItem = Annotated[TextContent | ImageContent, Field(discriminator='type')]` `module-attribute` ¶

`Message = Annotated[UserMessage | AssistantMessage | ToolResultMessage, Field(discriminator='role')]` `module-attribute` ¶

`AssistantMessageEvent = StartEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | DoneEvent | ErrorEvent` `module-attribute` ¶

`BaseModelWithAliases` ¶

`CostBreakdown` ¶

`Usage` ¶

`ModelCost` ¶

`TextContent` ¶

`ThinkingContent` ¶

`ImageContent` ¶

`ToolCall` ¶

`UserMessage` ¶

`AssistantMessage` ¶

`ToolResultMessage` ¶

`Tool` ¶

`from_pydantic(name, description, model_class)` `classmethod` ¶

`Model` ¶

`Context` ¶

`StreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None)` `dataclass` ¶

`SimpleStreamOptions(temperature=None, max_tokens=None, api_key=None, cancel_event=None, cache_retention=None, session_id=None, on_payload=None, headers=None, max_retry_delay_ms=None, metadata=None, reasoning=None, thinking_budgets=None)` `dataclass` ¶

`StartEvent(partial)` `dataclass` ¶

`TextStartEvent(content_index, partial)` `dataclass` ¶

`TextDeltaEvent(content_index, delta, partial)` `dataclass` ¶

`TextEndEvent(content_index, content, partial)` `dataclass` ¶

`ThinkingStartEvent(content_index, partial)` `dataclass` ¶

`ThinkingDeltaEvent(content_index, delta, partial)` `dataclass` ¶

`ThinkingEndEvent(content_index, content, partial)` `dataclass` ¶

`ToolCallStartEvent(content_index, partial)` `dataclass` ¶

`ToolCallDeltaEvent(content_index, delta, partial)` `dataclass` ¶

`ToolCallEndEvent(content_index, tool_call, partial)` `dataclass` ¶

`DoneEvent(reason, message)` `dataclass` ¶

`ErrorEvent(reason, error)` `dataclass` ¶