Skip to content

conversation.mdx

Latest commit

 

History

History
387 lines (267 loc) · 12.1 KB

conversation.mdx

File metadata and controls

387 lines (267 loc) · 12.1 KB
Raw
title Conversation
description Conversation protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

AI Conversation Memory Protocol

Multi-turn AI conversations with token budget management.

Enables context preservation, conversation history, and token optimization.

**Source:** `packages/spec/src/ai/conversation.zod.ts`

TypeScript Usage

import { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
import type { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';

// Validate data
const result = CodeContent.parse(data);

CodeContent

Properties

Property Type Required Description
type 'code' ✅
text string ✅ Code snippet
language string ✅
metadata Record<string, any> optional

ConversationAnalytics

Properties

Property Type Required Description
sessionId string ✅
totalMessages integer ✅
userMessages integer ✅
assistantMessages integer ✅
systemMessages integer ✅
totalTokens integer ✅
averageTokensPerMessage number ✅
peakTokenUsage integer ✅
pruningEvents integer ✅
summarizationEvents integer ✅
tokensSavedByPruning integer ✅
tokensSavedBySummarization integer ✅
duration number optional Session duration in seconds
firstMessageAt string optional ISO 8601 timestamp
lastMessageAt string optional ISO 8601 timestamp

ConversationContext

Properties

Property Type Required Description
sessionId string ✅ Conversation session ID
userId string optional User identifier
agentId string optional AI agent identifier
object string optional Related object (e.g., "case", "project")
recordId string optional Related record ID
scope Record<string, any> optional Additional context scope
systemMessage string optional System prompt/instructions
metadata Record<string, any> optional

ConversationMessage

Properties

Property Type Required Description
id string ✅ Unique message ID
timestamp string ✅ ISO 8601 timestamp
role Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'> ✅
content { type: 'text'; text: string; metadata?: Record<string, any> } | { type: 'image'; imageUrl: string; detail: Enum<'low' | 'high' | 'auto'>; metadata?: Record<string, any> } | { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } | { type: 'code'; text: string; language: string; metadata?: Record<string, any> }[] ✅ Message content (multimodal array)
functionCall { name: string; arguments: string; result?: string } optional Legacy function call
toolCalls { id: string; type: Enum<'function'>; function: object }[] optional Tool calls
toolCallId string optional Tool call ID this message responds to
name string optional Name of the function/user
tokens { promptTokens: integer; completionTokens: integer; totalTokens: integer } optional Token usage for this message
cost number optional Cost for this message in USD
pinned boolean ✅ Prevent removal during pruning
importance number optional Importance score for pruning
embedding number[] optional Vector embedding for semantic search
metadata Record<string, any> optional

ConversationSession

Properties

Property Type Required Description
id string ✅ Unique session ID
name string optional Session name/title
context { sessionId: string; userId?: string; agentId?: string; object?: string; … } ✅
modelId string optional AI model ID
tokenBudget { maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens: integer; … } ✅
messages { id: string; timestamp: string; role: Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>; content: { type: 'text'; text: string; metadata?: Record<string, any> } | { type: 'image'; imageUrl: string; detail: Enum<'low' | 'high' | 'auto'>; metadata?: Record<string, any> } | { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } | { type: 'code'; text: string; language: string; metadata?: Record<string, any> }[]; … }[] ✅
tokens { promptTokens: integer; completionTokens: integer; totalTokens: integer; budgetLimit: integer; … } optional
totalTokens { promptTokens: integer; completionTokens: integer; totalTokens: integer } optional Total tokens across all messages
totalCost number optional Total cost for this session in USD
status Enum<'active' | 'paused' | 'completed' | 'archived'> ✅
createdAt string ✅ ISO 8601 timestamp
updatedAt string ✅ ISO 8601 timestamp
expiresAt string optional ISO 8601 timestamp
metadata Record<string, any> optional

ConversationSummary

Properties

Property Type Required Description
summary string ✅ Conversation summary
keyPoints string[] optional Key discussion points
originalTokens integer ✅ Original token count
summaryTokens integer ✅ Summary token count
tokensSaved integer ✅ Tokens saved
messageRange { startIndex: integer; endIndex: integer } ✅ Range of messages summarized
generatedAt string ✅ ISO 8601 timestamp
modelId string optional Model used for summarization

FileContent

Properties

Property Type Required Description
type 'file' ✅
fileUrl string ✅ File attachment URL
mimeType string ✅ MIME type
fileName string optional
metadata Record<string, any> optional

FunctionCall

Properties

Property Type Required Description
name string ✅ Function name
arguments string ✅ JSON string of function arguments
result string optional Function execution result

ImageContent

Properties

Property Type Required Description
type 'image' ✅
imageUrl string ✅ Image URL
detail Enum<'low' | 'high' | 'auto'> ✅
metadata Record<string, any> optional

MessageContent

Union Options

This schema accepts one of the following structures:

Option 1

Type: text

Properties

Property Type Required Description
type 'text' ✅
text string ✅ Text content
metadata Record<string, any> optional

Option 2

Type: image

Properties

Property Type Required Description
type 'image' ✅
imageUrl string ✅ Image URL
detail Enum<'low' | 'high' | 'auto'> ✅
metadata Record<string, any> optional

Option 3

Type: file

Properties

Property Type Required Description
type 'file' ✅
fileUrl string ✅ File attachment URL
mimeType string ✅ MIME type
fileName string optional
metadata Record<string, any> optional

Option 4

Type: code

Properties

Property Type Required Description
type 'code' ✅
text string ✅ Code snippet
language string ✅
metadata Record<string, any> optional

MessageContentType

Allowed Values

  • text
  • image
  • file
  • code
  • structured

MessagePruningEvent

Properties

Property Type Required Description
timestamp string ✅ Event timestamp
prunedMessages { messageId: string; role: Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>; tokens: integer; importance?: number }[] ✅
tokensFreed integer ✅
messagesRemoved integer ✅
remainingTokens integer ✅
remainingMessages integer ✅

MessageRole

Allowed Values

  • system
  • user
  • assistant
  • function
  • tool

TextContent

Properties

Property Type Required Description
type 'text' ✅
text string ✅ Text content
metadata Record<string, any> optional

TokenBudgetConfig

Properties

Property Type Required Description
maxTokens integer ✅ Maximum total tokens
maxPromptTokens integer optional Max tokens for prompt
maxCompletionTokens integer optional Max tokens for completion
reserveTokens integer ✅ Reserve tokens for system messages
bufferPercentage number ✅ Buffer percentage (0.1 = 10%)
strategy Enum<'fifo' | 'importance' | 'semantic' | 'sliding_window' | 'summary'> ✅
slidingWindowSize integer optional Number of recent messages to keep
minImportanceScore number optional Minimum importance to keep
semanticThreshold number optional Semantic similarity threshold
enableSummarization boolean ✅ Enable context summarization
summarizationThreshold integer optional Trigger summarization at N tokens
summaryModel string optional Model ID for summarization
warnThreshold number ✅ Warn at % of budget (0.8 = 80%)

TokenBudgetStrategy

Allowed Values

  • fifo
  • importance
  • semantic
  • sliding_window
  • summary

TokenUsageStats

Properties

Property Type Required Description
promptTokens integer ✅
completionTokens integer ✅
totalTokens integer ✅
budgetLimit integer ✅
budgetUsed integer ✅
budgetRemaining integer ✅
budgetPercentage number ✅ Usage as percentage of budget
messageCount integer ✅
prunedMessageCount integer ✅
summarizedMessageCount integer ✅

ToolCall

Properties

Property Type Required Description
id string ✅ Tool call ID
type Enum<'function'> ✅
function { name: string; arguments: string; result?: string } ✅