@riotprompt/riotprompt 0.0.8 → 0.0.9

package/dist/conversation.d.ts

@@ -0,0 +1,271 @@
+import { Model } from './chat';
+import { ContextManager, DynamicContentItem } from './context-manager';
+import { LogConfig } from './conversation-logger';
+import { Content } from './items/content';
+import { Context } from './items/context';
+import { Instruction } from './items/instruction';
+import { Section } from './items/section';
+import { Prompt } from './prompt';
+import { TokenBudgetConfig, TokenUsage, CompressionStrategy } from './token-budget';
+import * as Formatter from "./formatter";
+/**
+ * Options for injecting context
+ */
+export interface InjectOptions {
+    position?: 'end' | 'before-last' | 'after-system' | number;
+    format?: 'structured' | 'inline' | 'reference';
+    deduplicate?: boolean;
+    deduplicateBy?: 'id' | 'content' | 'hash';
+    priority?: 'high' | 'medium' | 'low';
+    weight?: number;
+    category?: string;
+    source?: string;
+}
+/**
+ * Represents a tool call made by the assistant
+ */
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Message in a conversation (compatible with OpenAI ChatCompletionMessageParam)
+ */
+export interface ConversationMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+/**
+ * Configuration for ConversationBuilder
+ */
+export interface ConversationBuilderConfig {
+    model: Model;
+    formatter?: Formatter.Instance;
+    trackContext?: boolean;
+    deduplicateContext?: boolean;
+}
+/**
+ * Metadata about the conversation
+ */
+export interface ConversationMetadata {
+    model: Model;
+    created: Date;
+    lastModified: Date;
+    messageCount: number;
+    toolCallCount: number;
+}
+/**
+ * Internal state of a conversation
+ */
+export interface ConversationState {
+    messages: ConversationMessage[];
+    metadata: ConversationMetadata;
+    contextProvided: Set<string>;
+    contextManager: ContextManager;
+}
+/**
+ * Serializable conversation state for persistence
+ */
+export interface SerializedConversation {
+    messages: ConversationMessage[];
+    metadata: Omit<ConversationMetadata, 'created' | 'lastModified'> & {
+        created: string;
+        lastModified: string;
+    };
+    contextProvided: string[];
+}
+/**
+ * ConversationBuilder manages multi-turn conversations with full lifecycle support.
+ *
+ * Features:
+ * - Initialize from RiotPrompt prompts
+ * - Add messages of any type (system, user, assistant, tool)
+ * - Handle tool calls and results
+ * - Inject dynamic context
+ * - Clone for parallel exploration
+ * - Serialize/deserialize for persistence
+ *
+ * @example
+ * ```typescript
+ * // Create from prompt
+ * const conversation = ConversationBuilder.create()
+ *   .fromPrompt(prompt, 'gpt-4o')
+ *   .build();
+ *
+ * // Add messages
+ * conversation.addUserMessage('Analyze this code');
+ *
+ * // Handle tool calls
+ * conversation.addAssistantWithToolCalls(null, toolCalls);
+ * conversation.addToolResult(toolCallId, result);
+ *
+ * // Export
+ * const messages = conversation.toMessages();
+ * ```
+ */
+export declare class ConversationBuilder {
+    private state;
+    private config;
+    private logger;
+    private budgetManager?;
+    private conversationLogger?;
+    private constructor();
+    /**
+     * Create a new ConversationBuilder instance
+     */
+    static create(config?: Partial<ConversationBuilderConfig>, logger?: any): ConversationBuilder;
+    /**
+     * Initialize conversation from a RiotPrompt prompt
+     */
+    fromPrompt(prompt: Prompt, model?: Model): this;
+    /**
+     * Add a system message
+     */
+    addSystemMessage(content: string | Section<Instruction>): this;
+    /**
+     * Add a user message (with automatic budget management)
+     */
+    addUserMessage(content: string | Section<Content>): this;
+    /**
+     * Add an assistant message
+     */
+    addAssistantMessage(content: string | null): this;
+    /**
+     * Add an assistant message with tool calls
+     */
+    addAssistantWithToolCalls(content: string | null, toolCalls: ToolCall[]): this;
+    /**
+     * Add a tool result message
+     */
+    addToolResult(toolCallId: string, content: string, toolName?: string): this;
+    /**
+     * Alias for addToolResult (more intuitive naming)
+     */
+    addToolMessage(toolCallId: string, content: string, toolName?: string): this;
+    /**
+     * Inject context into the conversation with advanced options
+     *
+     * @param context - Array of content items to inject
+     * @param options - Injection options (position, format, deduplication, etc.)
+     */
+    injectContext(context: DynamicContentItem[], options?: InjectOptions): this;
+    /**
+     * Inject system-level context
+     */
+    injectSystemContext(context: Section<Context> | string): this;
+    /**
+     * Get the number of messages in the conversation
+     */
+    getMessageCount(): number;
+    /**
+     * Get the last message in the conversation
+     */
+    getLastMessage(): ConversationMessage | undefined;
+    /**
+     * Get all messages
+     */
+    getMessages(): ConversationMessage[];
+    /**
+     * Check if conversation has any tool calls
+     */
+    hasToolCalls(): boolean;
+    /**
+     * Get conversation metadata
+     */
+    getMetadata(): ConversationMetadata;
+    /**
+     * Export messages in OpenAI format
+     */
+    toMessages(): ConversationMessage[];
+    /**
+     * Serialize conversation to JSON
+     */
+    toJSON(): string;
+    /**
+     * Restore conversation from JSON
+     */
+    static fromJSON(json: string, config?: Partial<ConversationBuilderConfig>, logger?: any): ConversationBuilder;
+    /**
+     * Clone the conversation for parallel exploration
+     */
+    clone(): ConversationBuilder;
+    /**
+     * Truncate conversation to last N messages
+     */
+    truncate(maxMessages: number): this;
+    /**
+     * Remove all messages of a specific type
+     */
+    removeMessagesOfType(role: 'system' | 'user' | 'assistant' | 'tool'): this;
+    /**
+     * Get the context manager
+     */
+    getContextManager(): ContextManager;
+    /**
+     * Get conversation state (for conditional injection)
+     */
+    getState(): ConversationState;
+    /**
+     * Add a system message using semantic builder
+     */
+    asSystem(content: string | Section<Instruction>): this;
+    /**
+     * Add a user message using semantic builder
+     */
+    asUser(content: string | Section<Content>): this;
+    /**
+     * Add an assistant message using semantic builder
+     */
+    asAssistant(content: string | null, toolCalls?: ToolCall[]): this;
+    /**
+     * Add a tool result message using semantic builder
+     */
+    asTool(callId: string, result: any, metadata?: Record<string, any>): this;
+    /**
+     * Configure token budget
+     */
+    withTokenBudget(config: TokenBudgetConfig): this;
+    /**
+     * Configure conversation logging
+     */
+    withLogging(config: LogConfig): this;
+    /**
+     * Save conversation log
+     */
+    saveLog(): Promise<string>;
+    /**
+     * Get current token usage
+     */
+    getTokenUsage(): TokenUsage;
+    /**
+     * Manually compress conversation
+     */
+    compress(_strategy?: CompressionStrategy): this;
+    /**
+     * Build and return the builder (for fluent API compatibility)
+     */
+    build(): this;
+    /**
+     * Calculate position for context injection
+     */
+    private calculatePosition;
+    /**
+     * Format context item based on format option
+     */
+    private formatContextItem;
+    /**
+     * Update metadata after state changes
+     */
+    private updateMetadata;
+}
+/**
+ * Export the builder for use in other modules
+ */
+export default ConversationBuilder;