Documentation Index
Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
Use this file to discover all available pages before exploring further.
The @mariozechner/pi-ai package defines message types and context structures for LLM conversations.
Import
import type {
Context,
Message,
UserMessage,
AssistantMessage,
ToolResultMessage,
} from "@mariozechner/pi-ai";
Context
The conversation context passed to stream() and complete() functions.
interface Context {
systemPrompt: string;
messages: Message[];
tools?: Tool[];
}
System prompt that defines the agent’s behavior and capabilities
Conversation history (user, assistant, and tool result messages)
Available tools the model can invoke
Example
const context: Context = {
systemPrompt: "You are a helpful coding assistant.",
messages: [
{
role: "user",
content: "Write a function to reverse a string",
timestamp: Date.now(),
},
],
tools: [
{
type: "function",
function: {
name: "execute_code",
description: "Execute code",
parameters: {
type: "object",
properties: {
code: { type: "string" },
},
},
},
},
],
};
Message Types
UserMessage
A message from the user.
interface UserMessage {
role: "user";
content: string | Content[];
timestamp: number;
}
content
string | Content[]
required
Message content (text or mixed content)
Timestamp in milliseconds since epoch
Example
const userMessage: UserMessage = {
role: "user",
content: "What's in this image?",
timestamp: Date.now(),
};
// With image attachment
const userMessageWithImage: UserMessage = {
role: "user",
content: [
{ type: "text", text: "What's in this image?" },
{ type: "image", data: base64ImageData, mimeType: "image/png" },
],
timestamp: Date.now(),
};
AssistantMessage
A message from the AI assistant.
interface AssistantMessage {
role: "assistant";
content: Content[];
usage?: Usage;
timestamp: number;
stopReason?: string;
}
Message content (text, thinking, tool calls)
Timestamp in milliseconds since epoch
Why generation stopped (“stop”, “length”, “tool_use”, etc.)
Example
const assistantMessage: AssistantMessage = {
role: "assistant",
content: [
{ type: "text", text: "Here's a reverse function:" },
{ type: "text", text: "```typescript\nfunction reverse(s: string) {\n return s.split('').reverse().join('');\n}\n```" },
],
usage: {
input: 150,
output: 50,
cacheRead: 0,
cacheWrite: 0,
cost: { input: 0.00045, output: 0.00075, cacheRead: 0, cacheWrite: 0, total: 0.0012 },
},
timestamp: Date.now(),
stopReason: "stop",
};
interface ToolResultMessage {
role: "toolResult";
toolCallId: string;
toolName: string;
content: Content[];
timestamp: number;
isError?: boolean;
}
ID of the tool call this result corresponds to
Name of the tool that was executed
Timestamp in milliseconds since epoch
Whether the tool execution failed
Example
const toolResult: ToolResultMessage = {
role: "toolResult",
toolCallId: "call_123",
toolName: "execute_code",
content: [
{ type: "text", text: "Output: hello\nExit code: 0" },
],
timestamp: Date.now(),
isError: false,
};
Content Types
TextContent
Plain text content.
interface TextContent {
type: "text";
text: string;
textSignature?: string;
}
ThinkingContent
Reasoning/thinking content (for extended thinking models).
interface ThinkingContent {
type: "thinking";
thinking: string;
thinkingSignature?: string;
redacted?: boolean;
}
Whether the thinking was redacted by safety filters
ImageContent
Image attachment.
interface ImageContent {
type: "image";
data: string; // base64 encoded
mimeType: string; // e.g., "image/jpeg", "image/png"
}
interface ToolCall {
type: "toolCall";
id: string;
name: string;
arguments: Record<string, any>;
thoughtSignature?: string;
}
Usage
Token usage statistics.
interface Usage {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
cost: {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
total: number;
};
}
interface Tool {
type: "function";
function: {
name: string;
description: string;
parameters: JSONSchema;
};
}
Example
const tool: Tool = {
type: "function",
function: {
name: "get_weather",
description: "Get the current weather for a location",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City name (e.g., 'San Francisco')",
},
unit: {
type: "string",
enum: ["celsius", "fahrenheit"],
description: "Temperature unit",
},
},
required: ["location"],
},
},
};