Module sdk 

Stable SDK-facing API surface for embedding Pi as a library.

This module is the supported entry point for external library consumers. Prefer importing from pi::sdk instead of deep internal modules.

Examples

use pi::sdk::{AgentEvent, Message, ToolDefinition};

let _events: Vec<AgentEvent> = Vec::new();
let _messages: Vec<Message> = Vec::new();
let _tools: Vec<ToolDefinition> = Vec::new();

Internal implementation types are intentionally not part of this surface.

use pi::sdk::RpcSharedState;

Structs

AbortHandle

Handle to request an abort of an in-flight agent run.

AbortSignal

Signal for observing abort requests.

Agent

The agent runtime that orchestrates LLM calls and tool execution.

AgentConfig

Configuration for the agent.

AgentSession

AgentSessionHandle

Lightweight handle for programmatic embedding.

AgentSessionState

Snapshot of the current agent session state.

AssistantMessage

An assistant message.

Config

Main configuration structure.

Cost

Cost breakdown in dollars.

CustomMessage

A custom message injected by the host or extensions.

EventListeners

Collection of session-level event listeners.

ExtensionManager

Extension manager for handling loaded extensions.

ExtensionPolicy

ExtensionRegion

RAII guard for extension lifecycle with structured concurrency guarantees.

ImageContent

Image content block.

Model

A model definition loaded from the models registry.

ModelCost

Model pricing per million tokens.

ModelEntry

ModelRegistry

ProviderContext

Inputs to a single completion request.

ProviderThinkingBudgets

Custom thinking token budgets per level.

RpcBashResult

Bash execution result returned by RPC bash.

RpcCancelledResult

Result payload for new_session and switch_session.

RpcCommandInfo

Slash command metadata returned by RPC get_commands.

RpcCompactionResult

Compaction result returned by RPC compact.

RpcCycleModelResult

Result payload returned by RPC cycle_model.

RpcExportHtmlResult

Export HTML response payload.

RpcForkMessage

Forkable message entry returned by RPC get_fork_messages.

RpcForkResult

Result payload returned by RPC fork.

RpcLastAssistantText

Last-assistant-text response payload.

RpcModelInfo

Model metadata exposed by RPC APIs.

RpcSessionState

Session state payload returned by RPC get_state.

RpcSessionStats

Session stats payload returned by RPC get_session_stats.

RpcThinkingLevelResult

Result payload returned by RPC cycle_thinking_level.

RpcTokenStats

Session-level token aggregates returned by RPC get_session_stats.

RpcTransportClient

Subprocess-backed SDK transport for pi --mode rpc.

RpcTransportOptions

Process-boundary transport options for SDK callers that prefer RPC mode.

Session

A session manages conversation state and persistence.

SessionOptions

SDK session construction options.

StreamOptions

Options that control streaming completion behavior.

SubscriptionId

Opaque identifier for an event subscription.

TextContent

Text content block.

ThinkingContent

Thinking/reasoning content block.

ToolCall

Tool call content block.

ToolDef

A tool definition exposed to the model.

ToolOutput

Tool execution output.

ToolRegistry

Registry of enabled tools for a Pi run.

ToolResultMessage

A tool result message.

ToolUpdate

Incremental update during tool execution.

Usage

Token usage and cost tracking.

UserMessage

A user message.

Enums

AgentEvent

Events emitted by the agent during execution.

ContentBlock

A content block in a message.

Error

Main error type for the Pi application.

InputType

Input types supported by a model.

Message

A message in a conversation.

QueueMode

RpcExtensionUiResponse

Extension UI response payload used by RPC extension_ui_response.

SessionPromptResult

Prompt completion payload returned by SessionTransport.

SessionTransport

Unified adapter over in-process and subprocess-backed session control.

SessionTransportEvent

Event wrapper used by the unified SessionTransport callback.

SessionTransportState

Unified session state snapshot across in-process and RPC transports.

StopReason

Why a response ended.

StreamEvent

Streaming event from a provider.

ThinkingLevel

Extended thinking level.

UserContent

User message content - either plain text or blocks.

Constants

BUILTIN_TOOL_NAMES

All built-in tool names.

Traits

Provider

An LLM backend capable of streaming assistant output (and tool calls).

Tool

A tool that can be executed by the agent.

ToolFactory

Hook for assembling the session’s ToolRegistry.

Functions

all_tool_definitions

Return ToolDefinition schemas for all built-in tools.

create_agent_session

Create a fully configured embeddable agent session.

create_all_tools

Create all built-in tools configured for cwd.

create_bash_tool

Create a bash tool configured for cwd.

create_edit_tool

Create an edit tool configured for cwd.

create_find_tool

Create a find tool configured for cwd.

create_grep_tool

Create a grep tool configured for cwd.

create_hashline_edit_tool

Create a hashline edit tool configured for cwd.

create_ls_tool

Create an ls tool configured for cwd.

create_read_tool

Create a read tool configured for cwd.

create_write_tool

Create a write tool configured for cwd.

default_tool_registry

Build the same ToolRegistry create_agent_session uses by default.

tool_to_definition

Convert a Tool into its ToolDefinition schema.

Type Aliases

EventSubscriber

OnStreamEvent

Callback invoked for every raw provider StreamEvent.

OnToolEnd

Callback invoked when a tool execution ends.

OnToolStart

Callback invoked when a tool execution starts.

Result

Result type alias using our error type.

ToolDefinition

Stable alias for model-exposed tool schema definitions.