Context & Messages

Message types and context structure for LLM conversations

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[];
}

systemPrompt · string · required

System prompt that defines the agent’s behavior and capabilities

messages · Message[] · required

Conversation history (user, assistant, and tool result messages)

tools · Tool[]

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;
}

role · 'user' · required

Message role

content · string | Content[] · required

Message content (text or mixed content)

timestamp · number · required

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;
}

role · 'assistant' · required

Message role

content · Content[] · required

Message content (text, thinking, tool calls)

usage · Usage

Token usage statistics

timestamp · number · required

Timestamp in milliseconds since epoch

stopReason · string

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",
};

ToolResultMessage

The result of a tool execution.

interface ToolResultMessage {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  content: Content[];
  timestamp: number;
  isError?: boolean;
}

role · 'toolResult' · required

Message role

toolCallId · string · required

ID of the tool call this result corresponds to

toolName · string · required

Name of the tool that was executed

content · Content[] · required

Tool result content

timestamp · number · required

Timestamp in milliseconds since epoch

isError · boolean

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;
}

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"
}

ToolCall

Tool invocation request.

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;
  };
}

input · number

Input tokens consumed

output · number

Output tokens generated

cacheRead · number

Tokens read from cache

cacheWrite · number

Tokens written to cache

cost · object

Cost breakdown in USD

Tool Definition

Tool definitions use JSON Schema format:

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"],
    },
  },
};