@riotprompt/riotprompt 0.0.8 → 0.0.9

package/dist/riotprompt.d.ts

@@ -13,7 +13,15 @@ export * as Loader from './loader';
 export * as Override from './override';
 export * as Builder from './builder';
 export * as Recipes from './recipes';
-export { cook, recipe, registerTemplates, getTemplates, clearTemplates } from './recipes';
+export { cook, recipe, registerTemplates, getTemplates, clearTemplates, generateToolGuidance } from './recipes';
+export { ConversationBuilder } from './conversation';
+export { ContextManager } from './context-manager';
+export { TokenCounter, TokenBudgetManager } from './token-budget';
+export { MessageBuilder, MessageTemplates } from './message-builder';
+export { ConversationLogger, ConversationReplayer } from './conversation-logger';
+export { ToolRegistry } from './tools';
+export { StrategyExecutor, IterationStrategyFactory } from './iteration-strategy';
+export { MetricsCollector, ReflectionReportGenerator } from './reflection';
 export type { Content } from './items/content';
 export type { Context } from './items/context';
 export type { Instruction } from './items/instruction';
@@ -25,4 +33,12 @@ export type { Prompt } from './prompt';
 export type { FormatOptions, SectionSeparator, SectionTitleProperty } from './formatter';
 export type { Model, Request } from './chat';
 export type { Logger } from './logger';
-export type { RecipeConfig, ContentItem, TemplateConfig } from './recipes';
+export type { RecipeConfig, ContentItem, TemplateConfig, ToolGuidanceConfig } from './recipes';
+export type { ConversationMessage, ConversationBuilderConfig, ConversationMetadata, ConversationState, InjectOptions, ToolCall } from './conversation';
+export type { DynamicContentItem, TrackedContextItem, ContextStats } from './context-manager';
+export type { TokenUsage, TokenBudgetConfig, CompressionStats, CompressionStrategy } from './token-budget';
+export type { SemanticRole, MessageMetadata } from './message-builder';
+export type { IterationStrategy, StrategyPhase, StrategyState, StrategyResult, StrategyContext, PhaseResult, ToolResult, LLMClient, ToolUsagePolicy, Insight } from './iteration-strategy';
+export type { ReflectionReport, ReflectionConfig, AgenticExecutionMetrics, ToolExecutionMetric, ToolStats, Recommendation, ToolEffectivenessAnalysis, PerformanceInsights, QualityAssessment } from './reflection';
+export type { LogConfig, LogFormat, LoggedConversation, ConversationLogMetadata, LoggedMessage, ToolCallLog, ConversationSummary, ReplayOptions, ReplayResult } from './conversation-logger';
+export type { Tool, ToolParameter, ToolContext, ToolExample, ToolCost, OpenAITool, AnthropicTool, ToolDefinition, ToolUsageStats } from './tools';

package/dist/riotprompt.js

@@ -20,5 +20,13 @@ import * as builder from './builder.js';
 export { builder as Builder };
 import * as recipes from './recipes.js';
 export { recipes as Recipes };
-export { clearTemplates, cook, getTemplates, recipe, registerTemplates } from './recipes.js';
+export { clearTemplates, cook, generateToolGuidance, getTemplates, recipe, registerTemplates } from './recipes.js';
+export { ConversationBuilder } from './conversation.js';
+export { ContextManager } from './context-manager.js';
+export { TokenBudgetManager, TokenCounter } from './token-budget.js';
+export { MessageBuilder, MessageTemplates } from './message-builder.js';
+export { ConversationLogger, ConversationReplayer } from './conversation-logger.js';
+export { ToolRegistry } from './tools.js';
+export { IterationStrategyFactory, StrategyExecutor } from './iteration-strategy.js';
+export { MetricsCollector, ReflectionReportGenerator } from './reflection.js';
 //# sourceMappingURL=riotprompt.js.map

package/dist/riotprompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"riotprompt.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"riotprompt.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/token-budget.d.ts

@@ -0,0 +1,177 @@
+import { ConversationMessage } from './conversation';
+import { Model } from './chat';
+/**
+ * Token usage information
+ */
+export interface TokenUsage {
+    used: number;
+    max: number;
+    remaining: number;
+    percentage: number;
+}
+/**
+ * Compression statistics
+ */
+export interface CompressionStats {
+    messagesBefore: number;
+    messagesAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    strategy: CompressionStrategy;
+}
+/**
+ * Compression strategy
+ */
+export type CompressionStrategy = 'priority-based' | 'fifo' | 'summarize' | 'adaptive';
+/**
+ * Token budget configuration
+ */
+export interface TokenBudgetConfig {
+    max: number;
+    reserveForResponse: number;
+    warningThreshold?: number;
+    strategy: CompressionStrategy;
+    onBudgetExceeded: 'compress' | 'error' | 'warn' | 'truncate';
+    preserveRecent?: number;
+    preserveSystem?: boolean;
+    preserveHighPriority?: boolean;
+    onWarning?: (usage: TokenUsage) => void;
+    onCompression?: (stats: CompressionStats) => void;
+}
+/**
+ * TokenCounter counts tokens using tiktoken for accurate model-specific counting.
+ *
+ * Features:
+ * - Model-specific token counting
+ * - Message overhead calculation
+ * - Tool call token estimation
+ * - Response token estimation
+ *
+ * @example
+ * ```typescript
+ * const counter = new TokenCounter('gpt-4o');
+ *
+ * const tokens = counter.count('Hello, world!');
+ * console.log(`Text uses ${tokens} tokens`);
+ *
+ * const messageTokens = counter.countMessage({
+ *   role: 'user',
+ *   content: 'What is the weather?'
+ * });
+ * ```
+ */
+export declare class TokenCounter {
+    private encoder;
+    private model;
+    private logger;
+    constructor(model: Model, logger?: any);
+    /**
+     * Count tokens in text
+     */
+    count(text: string): number;
+    /**
+     * Count tokens in a single message
+     */
+    countMessage(message: ConversationMessage): number;
+    /**
+     * Count tokens in entire conversation
+     */
+    countConversation(messages: ConversationMessage[]): number;
+    /**
+     * Count with additional overhead estimation
+     */
+    countWithOverhead(messages: ConversationMessage[], includeToolOverhead?: boolean): number;
+    /**
+     * Estimate tokens needed for response
+     */
+    estimateResponseTokens(messages: ConversationMessage[]): number;
+    /**
+     * Map RiotPrompt model to Tiktoken model
+     */
+    private mapToTiktokenModel;
+    /**
+     * Free encoder resources
+     */
+    dispose(): void;
+}
+/**
+ * TokenBudgetManager manages token budgets and compression strategies.
+ *
+ * Features:
+ * - Monitor token usage
+ * - Automatic compression when budget exceeded
+ * - Multiple compression strategies
+ * - Priority-based message retention
+ * - Usage statistics and callbacks
+ *
+ * @example
+ * ```typescript
+ * const manager = new TokenBudgetManager({
+ *   max: 8000,
+ *   reserveForResponse: 1000,
+ *   strategy: 'priority-based',
+ *   onBudgetExceeded: 'compress'
+ * }, 'gpt-4o');
+ *
+ * // Check if message can be added
+ * if (manager.canAddMessage(message)) {
+ *   messages.push(message);
+ * } else {
+ *   // Compress conversation
+ *   messages = manager.compress(messages);
+ *   messages.push(message);
+ * }
+ * ```
+ */
+export declare class TokenBudgetManager {
+    private config;
+    private counter;
+    private logger;
+    constructor(config: TokenBudgetConfig, model: Model, logger?: any);
+    /**
+     * Get current token usage
+     */
+    getCurrentUsage(messages: ConversationMessage[]): TokenUsage;
+    /**
+     * Get remaining tokens available
+     */
+    getRemainingTokens(messages: ConversationMessage[]): number;
+    /**
+     * Check if near token limit
+     */
+    isNearLimit(messages: ConversationMessage[], threshold?: number): boolean;
+    /**
+     * Check if a message can be added without exceeding budget
+     */
+    canAddMessage(message: ConversationMessage, currentMessages: ConversationMessage[]): boolean;
+    /**
+     * Compress messages according to strategy
+     */
+    compress(messages: ConversationMessage[]): ConversationMessage[];
+    /**
+     * Compress by priority (keep high-priority messages)
+     */
+    private compressByPriority;
+    /**
+     * Compress using FIFO (remove oldest first)
+     */
+    private compressFIFO;
+    /**
+     * Adaptive compression based on conversation phase
+     */
+    private compressAdaptive;
+    /**
+     * Calculate message priority for compression
+     */
+    private calculatePriority;
+    /**
+     * Truncate to exact number of messages
+     */
+    truncate(messages: ConversationMessage[], maxMessages: number): ConversationMessage[];
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+}
+export default TokenBudgetManager;

package/dist/token-budget.js

@@ -0,0 +1,404 @@
+import { encoding_for_model } from 'tiktoken';
+import { wrapLogger, DEFAULT_LOGGER } from './logger.js';
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== TOKEN COUNTER =====
+/**
+ * TokenCounter counts tokens using tiktoken for accurate model-specific counting.
+ *
+ * Features:
+ * - Model-specific token counting
+ * - Message overhead calculation
+ * - Tool call token estimation
+ * - Response token estimation
+ *
+ * @example
+ * ```typescript
+ * const counter = new TokenCounter('gpt-4o');
+ *
+ * const tokens = counter.count('Hello, world!');
+ * console.log(`Text uses ${tokens} tokens`);
+ *
+ * const messageTokens = counter.countMessage({
+ *   role: 'user',
+ *   content: 'What is the weather?'
+ * });
+ * ```
+ */ class TokenCounter {
+    /**
+     * Count tokens in text
+     */ count(text) {
+        if (!text) return 0;
+        return this.encoder.encode(text).length;
+    }
+    /**
+     * Count tokens in a single message
+     */ countMessage(message) {
+        let tokens = 4; // Base overhead per message
+        // Content tokens
+        if (message.content) {
+            tokens += this.count(message.content);
+        }
+        // Role tokens
+        tokens += 1;
+        // Tool call tokens
+        if (message.tool_calls) {
+            for (const toolCall of message.tool_calls){
+                tokens += this.count(JSON.stringify(toolCall));
+                tokens += 3; // Tool call overhead
+            }
+        }
+        // Tool result tokens
+        if (message.tool_call_id) {
+            tokens += this.count(message.tool_call_id);
+            tokens += 2; // Tool result overhead
+        }
+        return tokens;
+    }
+    /**
+     * Count tokens in entire conversation
+     */ countConversation(messages) {
+        let total = 3; // Conversation start overhead
+        for (const message of messages){
+            total += this.countMessage(message);
+        }
+        return total;
+    }
+    /**
+     * Count with additional overhead estimation
+     */ countWithOverhead(messages, includeToolOverhead = false) {
+        let total = this.countConversation(messages);
+        // Add tool definition overhead if tools are present
+        if (includeToolOverhead) {
+            const hasTools = messages.some((m)=>m.tool_calls && m.tool_calls.length > 0);
+            if (hasTools) {
+                total += 100; // Estimated tool definition overhead
+            }
+        }
+        return total;
+    }
+    /**
+     * Estimate tokens needed for response
+     */ estimateResponseTokens(messages) {
+        // Heuristic: average response is about 20% of input
+        const inputTokens = this.countConversation(messages);
+        return Math.max(500, Math.floor(inputTokens * 0.2));
+    }
+    /**
+     * Map RiotPrompt model to Tiktoken model
+     */ mapToTiktokenModel(model) {
+        switch(model){
+            case 'gpt-4o':
+            case 'gpt-4o-mini':
+                return 'gpt-4o';
+            case 'o1-preview':
+            case 'o1-mini':
+            case 'o1':
+            case 'o3-mini':
+            case 'o1-pro':
+                // O1 models use gpt-4o tokenization
+                return 'gpt-4o';
+            default:
+                return 'gpt-4o';
+        }
+    }
+    /**
+     * Free encoder resources
+     */ dispose() {
+        this.encoder.free();
+    }
+    constructor(model, logger){
+        _define_property(this, "encoder", void 0);
+        _define_property(this, "model", void 0);
+        _define_property(this, "logger", void 0);
+        this.model = model;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'TokenCounter');
+        // Map RiotPrompt models to Tiktoken models
+        const tiktokenModel = this.mapToTiktokenModel(model);
+        this.encoder = encoding_for_model(tiktokenModel);
+        this.logger.debug('Created TokenCounter', {
+            model
+        });
+    }
+}
+// ===== TOKEN BUDGET MANAGER =====
+/**
+ * TokenBudgetManager manages token budgets and compression strategies.
+ *
+ * Features:
+ * - Monitor token usage
+ * - Automatic compression when budget exceeded
+ * - Multiple compression strategies
+ * - Priority-based message retention
+ * - Usage statistics and callbacks
+ *
+ * @example
+ * ```typescript
+ * const manager = new TokenBudgetManager({
+ *   max: 8000,
+ *   reserveForResponse: 1000,
+ *   strategy: 'priority-based',
+ *   onBudgetExceeded: 'compress'
+ * }, 'gpt-4o');
+ *
+ * // Check if message can be added
+ * if (manager.canAddMessage(message)) {
+ *   messages.push(message);
+ * } else {
+ *   // Compress conversation
+ *   messages = manager.compress(messages);
+ *   messages.push(message);
+ * }
+ * ```
+ */ class TokenBudgetManager {
+    /**
+     * Get current token usage
+     */ getCurrentUsage(messages) {
+        const used = this.counter.countConversation(messages);
+        const max = this.config.max;
+        const remaining = Math.max(0, max - used - this.config.reserveForResponse);
+        const percentage = used / max * 100;
+        return {
+            used,
+            max,
+            remaining,
+            percentage
+        };
+    }
+    /**
+     * Get remaining tokens available
+     */ getRemainingTokens(messages) {
+        return this.getCurrentUsage(messages).remaining;
+    }
+    /**
+     * Check if near token limit
+     */ isNearLimit(messages, threshold) {
+        const usage = this.getCurrentUsage(messages);
+        const checkThreshold = threshold !== null && threshold !== void 0 ? threshold : this.config.warningThreshold;
+        const isNear = usage.percentage >= checkThreshold * 100;
+        if (isNear) {
+            var _this_config_onWarning, _this_config;
+            (_this_config_onWarning = (_this_config = this.config).onWarning) === null || _this_config_onWarning === void 0 ? void 0 : _this_config_onWarning.call(_this_config, usage);
+        }
+        return isNear;
+    }
+    /**
+     * Check if a message can be added without exceeding budget
+     */ canAddMessage(message, currentMessages) {
+        const currentTokens = this.counter.countConversation(currentMessages);
+        const messageTokens = this.counter.countMessage(message);
+        const total = currentTokens + messageTokens + this.config.reserveForResponse;
+        return total <= this.config.max;
+    }
+    /**
+     * Compress messages according to strategy
+     */ compress(messages) {
+        var _this_config_onCompression, _this_config;
+        const before = messages.length;
+        const tokensBefore = this.counter.countConversation(messages);
+        const targetTokens = this.config.max - this.config.reserveForResponse;
+        this.logger.debug('Compressing messages', {
+            before,
+            tokensBefore,
+            targetTokens,
+            strategy: this.config.strategy
+        });
+        // No compression needed
+        if (tokensBefore <= targetTokens) {
+            return messages;
+        }
+        let compressed;
+        switch(this.config.strategy){
+            case 'priority-based':
+                compressed = this.compressByPriority(messages, targetTokens);
+                break;
+            case 'fifo':
+                compressed = this.compressFIFO(messages, targetTokens);
+                break;
+            case 'adaptive':
+                compressed = this.compressAdaptive(messages, targetTokens);
+                break;
+            case 'summarize':
+                // For now, fall back to FIFO (summarization would require LLM call)
+                compressed = this.compressFIFO(messages, targetTokens);
+                break;
+            default:
+                compressed = this.compressFIFO(messages, targetTokens);
+        }
+        const tokensAfter = this.counter.countConversation(compressed);
+        const stats = {
+            messagesBefore: before,
+            messagesAfter: compressed.length,
+            tokensBefore,
+            tokensAfter,
+            tokensSaved: tokensBefore - tokensAfter,
+            strategy: this.config.strategy
+        };
+        (_this_config_onCompression = (_this_config = this.config).onCompression) === null || _this_config_onCompression === void 0 ? void 0 : _this_config_onCompression.call(_this_config, stats);
+        this.logger.info('Compressed conversation', stats);
+        return compressed;
+    }
+    /**
+     * Compress by priority (keep high-priority messages)
+     */ compressByPriority(messages, targetTokens) {
+        // Calculate priority for each message
+        const withPriority = messages.map((msg, idx)=>({
+                message: msg,
+                priority: this.calculatePriority(msg, idx, messages.length),
+                tokens: this.counter.countMessage(msg),
+                index: idx
+            }));
+        // Sort by priority (descending)
+        withPriority.sort((a, b)=>b.priority - a.priority);
+        // Keep highest priority messages that fit in budget
+        const kept = [];
+        let totalTokens = 0;
+        for (const item of withPriority){
+            if (totalTokens + item.tokens <= targetTokens) {
+                kept.push(item);
+                totalTokens += item.tokens;
+            }
+        }
+        // Sort back to original order
+        kept.sort((a, b)=>a.index - b.index);
+        return kept.map((item)=>item.message);
+    }
+    /**
+     * Compress using FIFO (remove oldest first)
+     */ compressFIFO(messages, targetTokens) {
+        var _this_config_preserveRecent;
+        const preserved = [];
+        let totalTokens = 0;
+        // Always preserve system messages if configured
+        const systemMessages = messages.filter((m)=>m.role === 'system');
+        if (this.config.preserveSystem) {
+            for (const msg of systemMessages){
+                preserved.push(msg);
+                totalTokens += this.counter.countMessage(msg);
+            }
+        }
+        // Preserve recent messages
+        const recentCount = (_this_config_preserveRecent = this.config.preserveRecent) !== null && _this_config_preserveRecent !== void 0 ? _this_config_preserveRecent : 3;
+        const recentMessages = messages.slice(-recentCount).filter((m)=>m.role !== 'system');
+        for (const msg of recentMessages){
+            if (!preserved.includes(msg)) {
+                const tokens = this.counter.countMessage(msg);
+                if (totalTokens + tokens <= targetTokens) {
+                    preserved.push(msg);
+                    totalTokens += tokens;
+                }
+            }
+        }
+        // Add older messages if space available
+        const otherMessages = messages.filter((m)=>!preserved.includes(m) && m.role !== 'system');
+        for(let i = otherMessages.length - 1; i >= 0; i--){
+            const msg = otherMessages[i];
+            const tokens = this.counter.countMessage(msg);
+            if (totalTokens + tokens <= targetTokens) {
+                preserved.unshift(msg);
+                totalTokens += tokens;
+            } else {
+                break;
+            }
+        }
+        // Sort to maintain conversation order
+        return messages.filter((m)=>preserved.includes(m));
+    }
+    /**
+     * Adaptive compression based on conversation phase
+     */ compressAdaptive(messages, targetTokens) {
+        const messageCount = messages.length;
+        // Early phase: minimal compression (keep most messages)
+        if (messageCount <= 5) {
+            return this.compressFIFO(messages, targetTokens);
+        }
+        // Mid phase: moderate compression
+        if (messageCount <= 15) {
+            // Use FIFO but preserve more recent messages
+            const modifiedConfig = {
+                ...this.config,
+                preserveRecent: 5
+            };
+            const tempManager = new TokenBudgetManager(modifiedConfig, 'gpt-4o', this.logger);
+            return tempManager.compressFIFO(messages, targetTokens);
+        }
+        // Late phase: aggressive compression (priority-based)
+        return this.compressByPriority(messages, targetTokens);
+    }
+    /**
+     * Calculate message priority for compression
+     */ calculatePriority(message, index, total) {
+        let priority = 1.0;
+        // System messages: highest priority
+        if (message.role === 'system') {
+            priority = 10.0;
+        }
+        // Recent messages: higher priority
+        const recencyBonus = index / total;
+        priority += recencyBonus * 2;
+        // Tool results: moderate priority
+        if (message.role === 'tool') {
+            priority += 0.5;
+        }
+        // Messages with tool calls: keep for context
+        if (message.tool_calls && message.tool_calls.length > 0) {
+            priority += 0.8;
+        }
+        return priority;
+    }
+    /**
+     * Truncate to exact number of messages
+     */ truncate(messages, maxMessages) {
+        if (messages.length <= maxMessages) {
+            return messages;
+        }
+        // Keep system messages + recent messages
+        const systemMessages = messages.filter((m)=>m.role === 'system');
+        const otherMessages = messages.filter((m)=>m.role !== 'system');
+        const recentOther = otherMessages.slice(-(maxMessages - systemMessages.length));
+        return [
+            ...systemMessages,
+            ...recentOther
+        ];
+    }
+    /**
+     * Dispose resources
+     */ dispose() {
+        this.counter.dispose();
+    }
+    constructor(config, model, logger){
+        _define_property(this, "config", void 0);
+        _define_property(this, "counter", void 0);
+        _define_property(this, "logger", void 0);
+        this.config = {
+            warningThreshold: 0.8,
+            preserveRecent: 3,
+            preserveSystem: true,
+            preserveHighPriority: true,
+            onWarning: ()=>{},
+            onCompression: ()=>{},
+            ...config
+        };
+        this.counter = new TokenCounter(model, logger);
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'TokenBudgetManager');
+        this.logger.debug('Created TokenBudgetManager', {
+            max: this.config.max,
+            strategy: this.config.strategy
+        });
+    }
+}
+
+export { TokenBudgetManager, TokenCounter, TokenBudgetManager as default };
+//# sourceMappingURL=token-budget.js.map