@riotprompt/riotprompt 0.0.7 → 0.0.9

package/dist/recipes.d.ts

@@ -1,326 +1,117 @@
 import { z } from 'zod';
+import { Model } from './chat';
+import { ConversationBuilder } from './conversation';
 import { Prompt } from './riotprompt';
-declare const ContentItemSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+import { TokenBudgetConfig } from './token-budget';
+import { Tool, ToolRegistry } from './tools';
+import { IterationStrategy, LLMClient, StrategyResult } from './iteration-strategy';
+declare const ContentItemSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     content: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     weight: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    content: string;
-    weight?: number | undefined;
-    title?: string | undefined;
-}, {
-    content: string;
-    weight?: number | undefined;
-    title?: string | undefined;
-}>, z.ZodObject<{
+}, z.core.$strip>, z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     weight: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    weight?: number | undefined;
-    title?: string | undefined;
-}, {
-    path: string;
-    weight?: number | undefined;
-    title?: string | undefined;
-}>, z.ZodObject<{
-    directories: z.ZodArray<z.ZodString, "many">;
+}, z.core.$strip>, z.ZodObject<{
+    directories: z.ZodArray<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     weight: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    directories: string[];
-    weight?: number | undefined;
-    title?: string | undefined;
-}, {
-    directories: string[];
-    weight?: number | undefined;
-    title?: string | undefined;
-}>]>;
+}, z.core.$strip>]>;
 declare const RecipeConfigSchema: z.ZodObject<{
     basePath: z.ZodString;
     logger: z.ZodDefault<z.ZodOptional<z.ZodAny>>;
-    overridePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    overridePaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     overrides: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    parameters: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>>>>;
-    persona: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    parameters: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>>>;
+    persona: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         content: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         path: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
-        directories: z.ZodArray<z.ZodString, "many">;
+    }, z.core.$strip>, z.ZodObject<{
+        directories: z.ZodArray<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>]>>;
-    instructions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    }, z.core.$strip>]>>;
+    instructions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         content: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         path: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
-        directories: z.ZodArray<z.ZodString, "many">;
+    }, z.core.$strip>, z.ZodObject<{
+        directories: z.ZodArray<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>]>, "many">>>;
-    content: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    }, z.core.$strip>]>>>>;
+    content: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         content: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         path: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
-        directories: z.ZodArray<z.ZodString, "many">;
+    }, z.core.$strip>, z.ZodObject<{
+        directories: z.ZodArray<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>]>, "many">>>;
-    context: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    }, z.core.$strip>]>>>>;
+    context: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         content: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         path: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>, z.ZodObject<{
-        directories: z.ZodArray<z.ZodString, "many">;
+    }, z.core.$strip>, z.ZodObject<{
+        directories: z.ZodArray<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         weight: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }, {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    }>]>, "many">>>;
+    }, z.core.$strip>]>>>>;
     extends: z.ZodOptional<z.ZodString>;
     template: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    parameters: Record<string, string | number | boolean | (string | number | boolean)[]>;
-    instructions: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[];
-    overrides: boolean;
-    basePath: string;
-    overridePaths: string[];
-    content: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[];
-    context: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[];
-    persona?: string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | undefined;
-    logger?: any;
-    extends?: string | undefined;
-    template?: string | undefined;
-}, {
-    basePath: string;
-    parameters?: Record<string, string | number | boolean | (string | number | boolean)[]> | undefined;
-    persona?: string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | undefined;
-    instructions?: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[] | undefined;
-    logger?: any;
-    overrides?: boolean | undefined;
-    overridePaths?: string[] | undefined;
-    content?: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[] | undefined;
-    context?: (string | {
-        content: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        path: string;
-        weight?: number | undefined;
-        title?: string | undefined;
-    } | {
-        directories: string[];
-        weight?: number | undefined;
-        title?: string | undefined;
-    })[] | undefined;
-    extends?: string | undefined;
-    template?: string | undefined;
-}>;
+    tools: z.ZodOptional<z.ZodAny>;
+    toolGuidance: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        minimal: "minimal";
+        detailed: "detailed";
+    }>, z.ZodObject<{
+        strategy: z.ZodEnum<{
+            adaptive: "adaptive";
+            minimal: "minimal";
+            prescriptive: "prescriptive";
+        }>;
+        includeExamples: z.ZodOptional<z.ZodBoolean>;
+        explainWhenToUse: z.ZodOptional<z.ZodBoolean>;
+        includeCategories: z.ZodOptional<z.ZodBoolean>;
+        customInstructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    toolCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 type RecipeConfig = z.infer<typeof RecipeConfigSchema>;
 type ContentItem = z.infer<typeof ContentItemSchema>;
+export interface ToolGuidanceConfig {
+    strategy: 'adaptive' | 'prescriptive' | 'minimal';
+    includeExamples?: boolean;
+    explainWhenToUse?: boolean;
+    includeCategories?: boolean;
+    customInstructions?: string;
+}
 export interface TemplateConfig {
     persona?: ContentItem;
     instructions?: ContentItem[];
     content?: ContentItem[];
     context?: ContentItem[];
+    tools?: Tool[] | ToolRegistry;
+    toolGuidance?: Partial<ToolGuidanceConfig> | 'auto' | 'minimal' | 'detailed';
 }
 /**
  * Register custom templates with the recipes system
@@ -349,6 +140,10 @@ export declare const getTemplates: () => Record<string, TemplateConfig>;
  * Clear all registered templates
  */
 export declare const clearTemplates: () => void;
+/**
+ * Generate tool guidance instructions based on strategy
+ */
+export declare const generateToolGuidance: (tools: Tool[], guidance: ToolGuidanceConfig | "auto" | "minimal" | "detailed") => string;
 export declare const cook: (config: Partial<RecipeConfig> & {
     basePath: string;
 }) => Promise<Prompt>;
@@ -362,6 +157,13 @@ export declare const recipe: (basePath: string) => {
     parameters: (parameters: any) => /*elided*/ any;
     overrides: (enabled: boolean) => /*elided*/ any;
     overridePaths: (paths: string[]) => /*elided*/ any;
+    tools: (tools: Tool[] | ToolRegistry) => /*elided*/ any;
+    toolRegistry: (registry: ToolRegistry) => /*elided*/ any;
+    toolGuidance: (guidance: ToolGuidanceConfig | "auto" | "minimal" | "detailed") => /*elided*/ any;
+    toolCategories: (categories: string[]) => /*elided*/ any;
     cook: () => Promise<Prompt>;
+    buildConversation: (model: Model, tokenBudget?: TokenBudgetConfig) => Promise<ConversationBuilder>;
+    getToolRegistry: () => ToolRegistry | undefined;
+    executeWith: (llm: LLMClient, strategy: IterationStrategy, tokenBudget?: TokenBudgetConfig) => Promise<StrategyResult>;
 };
 export type { RecipeConfig, ContentItem };

package/dist/recipes.js

@@ -1,5 +1,6 @@
 import path__default from 'path';
 import { z } from 'zod';
+import { ConversationBuilder } from './conversation.js';
 import { ParametersSchema } from './items/parameters.js';
 import { DEFAULT_LOGGER, wrapLogger } from './logger.js';
 import './items/weighted.js';
@@ -10,6 +11,9 @@ import { create } from './parser.js';
 import { create as create$2 } from './loader.js';
 import { create as create$1 } from './override.js';
 import './builder.js';
+import 'tiktoken';
+import { ToolRegistry } from './tools.js';
+import { StrategyExecutor } from './iteration-strategy.js';
 
 // ===== CONFIGURATION SCHEMAS =====
 const ContentItemSchema = z.union([
@@ -46,13 +50,34 @@ const RecipeConfigSchema = z.object({
     context: z.array(ContentItemSchema).optional().default([]),
     // Templates and inheritance
     extends: z.string().optional(),
-    template: z.string().optional()
+    template: z.string().optional(),
+    // Tool integration
+    tools: z.any().optional(),
+    toolGuidance: z.union([
+        z.enum([
+            'auto',
+            'minimal',
+            'detailed'
+        ]),
+        z.object({
+            strategy: z.enum([
+                'adaptive',
+                'prescriptive',
+                'minimal'
+            ]),
+            includeExamples: z.boolean().optional(),
+            explainWhenToUse: z.boolean().optional(),
+            includeCategories: z.boolean().optional(),
+            customInstructions: z.string().optional()
+        })
+    ]).optional(),
+    toolCategories: z.array(z.string()).optional()
 });
 // User-customizable template registry
 let TEMPLATES = {};
 /**
  * Register custom templates with the recipes system
- * 
+ *
  * @example
  * ```typescript
  * // Register your own templates
@@ -83,6 +108,99 @@ let TEMPLATES = {};
  */ const clearTemplates = ()=>{
     TEMPLATES = {};
 };
+// ===== TOOL GUIDANCE GENERATION =====
+/**
+ * Generate tool guidance instructions based on strategy
+ */ const generateToolGuidance = (tools, guidance)=>{
+    if (tools.length === 0) {
+        return '';
+    }
+    // Normalize guidance config
+    let config;
+    if (typeof guidance === 'string') {
+        switch(guidance){
+            case 'auto':
+            case 'detailed':
+                config = {
+                    strategy: 'adaptive',
+                    includeExamples: true,
+                    explainWhenToUse: true
+                };
+                break;
+            case 'minimal':
+                config = {
+                    strategy: 'minimal',
+                    includeExamples: false,
+                    explainWhenToUse: false
+                };
+                break;
+            default:
+                config = {
+                    strategy: 'adaptive'
+                };
+        }
+    } else {
+        config = guidance;
+    }
+    let output = '## Available Tools\n\n';
+    if (config.customInstructions) {
+        output += config.customInstructions + '\n\n';
+    }
+    // Group by category if enabled
+    if (config.includeCategories) {
+        const categorized = new Map();
+        tools.forEach((tool)=>{
+            const category = tool.category || 'General';
+            if (!categorized.has(category)) {
+                categorized.set(category, []);
+            }
+            categorized.get(category).push(tool);
+        });
+        categorized.forEach((categoryTools, category)=>{
+            output += `### ${category}\n\n`;
+            categoryTools.forEach((tool)=>{
+                output += formatToolGuidance(tool, config);
+            });
+        });
+    } else {
+        tools.forEach((tool)=>{
+            output += formatToolGuidance(tool, config);
+        });
+    }
+    return output;
+};
+const formatToolGuidance = (tool, config)=>{
+    let output = `**${tool.name}**`;
+    if (tool.cost) {
+        output += ` _(${tool.cost})_`;
+    }
+    output += `\n${tool.description}\n\n`;
+    if (config.strategy !== 'minimal') {
+        // Parameters
+        const required = tool.parameters.required || [];
+        const paramList = Object.entries(tool.parameters.properties).map(([name, param])=>{
+            const isRequired = required.includes(name);
+            return `- \`${name}\`${isRequired ? ' (required)' : ''}: ${param.description}`;
+        }).join('\n');
+        if (paramList) {
+            output += 'Parameters:\n' + paramList + '\n\n';
+        }
+        // When to use (adaptive and prescriptive)
+        if (config.explainWhenToUse && (config.strategy === 'adaptive' || config.strategy === 'prescriptive')) {
+            output += `**When to use:** ${tool.description}\n\n`;
+        }
+        // Examples
+        if (config.includeExamples && tool.examples && tool.examples.length > 0) {
+            output += '**Examples:**\n';
+            tool.examples.forEach((example)=>{
+                output += `- ${example.scenario}: \`${tool.name}(${JSON.stringify(example.params)})\`\n`;
+            });
+            output += '\n';
+        }
+    }
+    output += '---\n\n';
+    return output;
+};
 // ===== CORE RECIPE ENGINE =====
 const cook = async (config)=>{
     // Parse and validate configuration with defaults
@@ -168,6 +286,19 @@ const cook = async (config)=>{
             loader: loader$1,
             parameters: finalConfig.parameters});
     }
+    // Generate tool guidance if tools are provided
+    if (finalConfig.tools) {
+        const tools = Array.isArray(finalConfig.tools) ? finalConfig.tools : finalConfig.tools.getAll();
+        // Filter by categories if specified
+        const filteredTools = finalConfig.toolCategories ? tools.filter((tool)=>finalConfig.toolCategories.includes(tool.category || '')) : tools;
+        if (filteredTools.length > 0 && finalConfig.toolGuidance) {
+            const guidance = generateToolGuidance(filteredTools, finalConfig.toolGuidance);
+            const toolSection = await parser$1.parse(guidance, {
+                parameters: finalConfig.parameters
+            });
+            instructionSection.add(toolSection);
+        }
+    }
     // Process content
     for (const item of finalConfig.content || []){
         await processContentItem(item, contentSection, 'content', {
@@ -284,10 +415,64 @@ const recipe = (basePath)=>{
             config.overridePaths = paths;
             return builder;
         },
-        cook: ()=>cook(config)
+        tools: (tools)=>{
+            config.tools = tools;
+            return builder;
+        },
+        toolRegistry: (registry)=>{
+            config.tools = registry;
+            return builder;
+        },
+        toolGuidance: (guidance)=>{
+            config.toolGuidance = guidance;
+            return builder;
+        },
+        toolCategories: (categories)=>{
+            config.toolCategories = categories;
+            return builder;
+        },
+        cook: ()=>cook(config),
+        buildConversation: async (model, tokenBudget)=>{
+            const prompt = await cook(config);
+            const conversation = ConversationBuilder.create({
+                model
+            }, config.logger);
+            conversation.fromPrompt(prompt, model);
+            // Apply token budget if provided
+            if (tokenBudget) {
+                conversation.withTokenBudget(tokenBudget);
+            }
+            return conversation;
+        },
+        getToolRegistry: ()=>{
+            if (config.tools instanceof ToolRegistry) {
+                return config.tools;
+            } else if (Array.isArray(config.tools)) {
+                const registry = ToolRegistry.create({}, config.logger);
+                registry.registerAll(config.tools);
+                return registry;
+            }
+            return undefined;
+        },
+        executeWith: async (llm, strategy, tokenBudget)=>{
+            const prompt = await cook(config);
+            const conversation = ConversationBuilder.create({
+                model: 'gpt-4o'
+            }, config.logger);
+            conversation.fromPrompt(prompt, 'gpt-4o');
+            if (tokenBudget) {
+                conversation.withTokenBudget(tokenBudget);
+            }
+            const registry = builder.getToolRegistry();
+            if (!registry) {
+                throw new Error('Tools must be configured to use executeWith');
+            }
+            const executor = new StrategyExecutor(llm, config.logger);
+            return executor.execute(conversation, registry, strategy);
+        }
     };
     return builder;
 };
 
-export { clearTemplates, cook, getTemplates, recipe, registerTemplates };
+export { clearTemplates, cook, generateToolGuidance, getTemplates, recipe, registerTemplates };
 //# sourceMappingURL=recipes.js.map