@tstdl/base 0.93.191 → 0.93.193

package/ai/prompts/instructions-formatter.js

@@ -1,7 +1,8 @@
 import { memoize } from '../../utils/function/memoize.js';
-import { hasOwnProperty, objectEntries } from '../../utils/object/object.js';
+import { objectEntries } from '../../utils/object/object.js';
 import { assertDefined, isArray, isDefined, isObject, isString } from '../../utils/type-guards.js';
 const whitespacePattern = /^\s*/;
+const INDENT_SIZE = 4;
 // --- Factories ---
 function list(style, instructionOrItems, itemsOrNothing) {
     const instruction = isString(instructionOrItems) ? instructionOrItems : undefined;
@@ -20,10 +21,9 @@ export function unorderedList(instructionOrItems, itemsOrNothing) {
 }
 // --- Type Guards ---
 function isInstructionsList(obj) {
-    return isObject(obj) && hasOwnProperty(obj, 'style') && hasOwnProperty(obj, 'items');
+    return isObject(obj) && ('style' in obj) && ('items' in obj);
 }
-// --- Formatter Logic ---
-const INDENT_SIZE = 4;
+// --- Formatting Helpers ---
 function getPrefix(style, index, sectionDepth) {
     switch (style) {
         case 'ordered':
@@ -36,20 +36,23 @@ function getPrefix(style, index, sectionDepth) {
             return '';
     }
 }
+function getIndent(context) {
+    return context.style == 'sections' ? '' : ' '.repeat(context.indentDepth * INDENT_SIZE);
+}
 function dedent(text) {
     const lines = text.split('\n');
     if (lines.length <= 1) {
         return text.trim();
     }
     // Remove leading empty line if any (common in template literals)
-    if (lines[0].trim().length === 0) {
+    if (lines[0].trim().length == 0) {
         lines.shift();
     }
     // Remove trailing empty line if any
-    if (lines.length > 0 && lines.at(-1).trim().length === 0) {
+    if (lines.length > 0 && lines.at(-1).trim().length == 0) {
         lines.pop();
     }
-    if (lines.length === 0) {
+    if (lines.length == 0) {
         return '';
     }
     // Find minimum indentation (excluding empty lines)
@@ -84,118 +87,103 @@ function formatWithHangingIndent(text, baseIndent, prefix) {
         ...lines.slice(1).map((line) => `${hangingSpacer}${line}`),
     ].join('\n');
 }
-/**
- * Main recursive formatter.
- */
-function processNode(node, context) {
-    // 0. Handle Strings
-    if (isString(node)) {
-        const isSection = context.style == 'sections';
-        const currentBaseIndent = ' '.repeat(isSection ? 0 : context.indentDepth * INDENT_SIZE);
-        return formatWithHangingIndent(dedent(node), currentBaseIndent, '');
-    }
-    // 1. Unwrap InstructionsList (The Wrapper)
-    // If the node is a wrapper, we adopt its style and instruction, then process its items.
-    if (isInstructionsList(node)) {
-        // Note: We don't print the "instruction" here (e.g., "Use Markdown").
-        // If this Wrapper is a root node, the instruction is usually printed by the caller or ignored.
-        // If this Wrapper is a value of a key, the key printer handles the instruction.
-        // However, if we have a "Root Wrapper" with an instruction (rare in your example), handle it:
-        const header = node.instruction ? `${dedent(node.instruction)}\n\n` : '';
-        // Determine next context
-        const nextContext = {
-            indentDepth: context.indentDepth, // Wrappers don't indent themselves, their content does
+function createNextContext(context, overrides = {}) {
+    return { ...context, isRoot: false, ...overrides };
+}
+// --- Node Processors ---
+function processString(node, context, prefix = '') {
+    return formatWithHangingIndent(dedent(node), getIndent(context), prefix);
+}
+function processWrapper(node, context, prefix = '') {
+    if (isDefined(node.instruction)) {
+        if (context.isRoot == true) {
+            const header = `${dedent(node.instruction)}\n\n`;
+            return header + processNode(node.items, createNextContext(context, { style: node.style }));
+        }
+        const header = formatWithHangingIndent(dedent(node.instruction), getIndent(context), prefix);
+        const nextContext = createNextContext(context, {
+            indentDepth: context.indentDepth + 1,
             style: node.style,
-            sectionDepth: node.style == 'sections' ? context.sectionDepth : context.sectionDepth, // Section depth increments internally
-        };
-        return header + processNode(node.items, nextContext);
+            sectionDepth: node.style == 'sections' ? context.sectionDepth : context.sectionDepth,
+        });
+        return `${header}\n${processNode(node.items, nextContext)}`;
     }
-    // Common Constants for this level
+    return processNode(node.items, createNextContext(context, { style: node.style }));
+}
+function processArray(node, context) {
+    const separator = context.style == 'sections' ? '\n\n' : '\n';
+    return node.map((item, index) => {
+        const prefix = getPrefix(context.style, index, context.sectionDepth);
+        if (isString(item)) {
+            return processString(item, context, prefix);
+        }
+        if (isInstructionsList(item)) {
+            return processWrapper(item, context, prefix);
+        }
+        return processNode(item, createNextContext(context));
+    }).join(separator);
+}
+function processObject(node, context) {
     const isSection = context.style == 'sections';
-    const currentBaseIndent = ' '.repeat(isSection ? 0 : context.indentDepth * INDENT_SIZE);
+    const baseIndent = getIndent(context);
     const separator = isSection ? '\n\n' : '\n';
-    // 2. Handle Arrays
-    if (isArray(node)) {
-        return node.map((item, index) => {
-            const prefix = getPrefix(context.style, index, context.sectionDepth);
-            if (isString(item)) {
-                return formatWithHangingIndent(dedent(item), currentBaseIndent, prefix);
-            }
-            return processNode(item, context);
-        }).join(separator);
-    }
-    // 3. Handle Objects (Key-Value Maps)
     return objectEntries(node).map(([key, value], index) => {
         const prefix = getPrefix(context.style, index, context.sectionDepth);
-        // Detect if the Value is a Wrapper (e.g. `Key: ordered(...)`)
-        // This allows us to pull the wrapper's "instruction" up to the Key line.
         const isValueWrapper = isInstructionsList(value);
         const effectiveValue = isValueWrapper ? value.items : value;
         const instruction = (isValueWrapper && isDefined(value.instruction)) ? ` ${dedent(value.instruction)}` : '';
-        const childStyle = isValueWrapper ? value.style : (isSection ? 'unordered' : 'unordered');
-        // Formatting the Header Line (The Key)
+        const childStyle = isValueWrapper ? value.style : 'unordered';
         let headerLine = '';
         if (isSection) {
-            // Header format: "# Key" or "# Key\n\nInstruction"
             const instructionPart = (instruction.length > 0) ? `\n\n${instruction.trim()}` : '';
-            headerLine = `${currentBaseIndent}${prefix}${key}${instructionPart}`;
+            headerLine = `${baseIndent}${prefix}${key}${instructionPart}`;
         }
         else {
-            // List format: "- **Key:**" or "- **Key:** Instruction"
-            const keyPart = `**${key}:**`;
-            headerLine = `${currentBaseIndent}${prefix}${keyPart}${instruction}`;
+            headerLine = `${baseIndent}${prefix}**${key}:**${instruction}`;
         }
-        // Determine context for the children
-        // If we are a Section, children reset indent to 0.
-        // If we are a List, children indent + 1.
-        const nextIndentDepth = isSection ? 0 : context.indentDepth + 1;
-        // If the child acts as a section (Wrapper was `sections(...)`), increment H-level.
-        const nextSectionDepth = (isValueWrapper && value.style == 'sections')
-            ? context.sectionDepth + 1
-            : context.sectionDepth;
-        // Recurse
-        // If the value is a simple string, we print it inline if possible, or block if it's long?
-        // Your requirement: Strings in objects are usually descriptions.
+        const nextContext = createNextContext(context, {
+            indentDepth: isSection ? 0 : context.indentDepth + 1,
+            sectionDepth: (isValueWrapper && value.style == 'sections') ? context.sectionDepth + 1 : context.sectionDepth,
+            style: childStyle,
+        });
         if (isString(effectiveValue)) {
-            // If it's a string, we treat it as content on the SAME line for lists (via hanging indent logic),
-            // or a new paragraph for Sections.
             if (isSection) {
-                // Section: Header \n\n Content
                 return `${headerLine}\n\n${dedent(effectiveValue)}`;
             }
-            // List: "- **Key:** Value"
-            // We need to construct the full string to calculate hanging indent correctly.
-            // headerLine already contains indentation + prefix + key.
-            // We strip the indentation to feed it into the formatting helper effectively.
             const fullLine = `${headerLine} ${dedent(effectiveValue)}`.trim();
-            return formatWithHangingIndent(fullLine, currentBaseIndent, '');
+            return formatWithHangingIndent(fullLine, baseIndent, '');
         }
-        // If Value is Object/Array/Wrapper
-        const body = processNode(effectiveValue, {
-            indentDepth: nextIndentDepth,
-            style: childStyle,
-            sectionDepth: nextSectionDepth,
-        });
+        const body = processNode(effectiveValue, nextContext);
         const bodySeparator = isSection ? '\n\n' : '\n';
-        // Edge case: If it's a section, we constructed the header, now append body.
-        // If it's a list, the header line serves as the parent item.
         return `${headerLine}${bodySeparator}${body}`;
     }).join(separator);
 }
+/**
+ * Main recursive formatter.
+ */
+function processNode(node, context) {
+    if (isString(node)) {
+        return processString(node, context);
+    }
+    if (isInstructionsList(node)) {
+        return processWrapper(node, context);
+    }
+    if (isArray(node)) {
+        return processArray(node, context);
+    }
+    return processObject(node, context);
+}
 function _formatInstructions(node, options = {}) {
-    // Heuristic: If passing a raw object, assume it's a Root Section unless specified otherwise.
-    // If passing a Wrapper, the Wrapper dictates the style.
     const initialStyle = isInstructionsList(node)
         ? node.style
-        : isArray(node)
+        : isArray(node) || isString(node)
             ? 'unordered'
-            : isString(node)
-                ? 'unordered'
-                : 'sections';
+            : 'sections';
     return processNode(node, {
         indentDepth: options.initialDepth ?? 0,
         sectionDepth: 1,
         style: initialStyle,
+        isRoot: true,
     }).trim();
 }
 const formatInstructionsMemoized = memoize(_formatInstructions, { weak: true });

package/ai/prompts/prompt-builder.d.ts

@@ -14,6 +14,8 @@ export declare class PromptBuilder {
     setTask(task: string): this;
     setSystemOutputSchema<Input = ObjectLiteral, Output = ObjectLiteral>(schema: SchemaTestable<Output>, examples?: FewShotExample<Input, Output>[]): this;
     setOutputSchema<Input = ObjectLiteral, Output = ObjectLiteral>(schema: SchemaTestable<Output>, examples?: FewShotExample<Input, Output>[]): this;
+    setSystemOutputExamples<Input = ObjectLiteral, Output = ObjectLiteral>(examples: FewShotExample<Input, Output>[]): this;
+    setOutputExamples<Input = ObjectLiteral, Output = ObjectLiteral>(examples: FewShotExample<Input, Output>[]): this;
     setSystemInstructionsOverride(override: ((instructions: Instructions) => Instructions | string) | undefined): this;
     setInstructionsOverride(override: ((instructions: Instructions) => Instructions | string) | undefined): this;
     setLanguage(language: string): this;

package/ai/prompts/prompt-builder.js

@@ -49,6 +49,14 @@ export class PromptBuilder {
         this.#outputExamples = examples;
         return this;
     }
+    setSystemOutputExamples(examples) {
+        this.#systemOutputExamples = examples;
+        return this;
+    }
+    setOutputExamples(examples) {
+        this.#outputExamples = examples;
+        return this;
+    }
     setSystemInstructionsOverride(override) {
         this.#systemInstructionsOverride = override;
         return this;
@@ -143,10 +151,13 @@ function buildPrompt(data) {
     if (isDefined(data.instructions) && (objectKeys(data.instructions).length > 0)) {
         instructions['**Instructions**'] = data.instructions;
     }
-    if (isDefined(data.outputSchema)) {
-        const schema = convertToOpenApiSchema(data.outputSchema);
-        const schemaJson = JSON.stringify(schema, null, 2);
-        instructions['**Output Schema**'] = `\`\`\`json\n${schemaJson}\n\`\`\``;
+    const hasOutputSchema = isDefined(data.outputSchema);
+    if (hasOutputSchema || isDefined(data.outputExamples)) {
+        if (hasOutputSchema) {
+            const schema = convertToOpenApiSchema(data.outputSchema);
+            const schemaJson = JSON.stringify(schema, null, 2);
+            instructions['**Output Schema**'] = `\`\`\`json\n${schemaJson}\n\`\`\``;
+        }
         instructions['**Output Schema Instructions**'] = unorderedList({
             'Schema Compliance': 'Generate valid JSON that strictly matches the provided schema.',
             'Nullable fields with missing data': 'Must be set to literal `null`, not the string "null".',

package/ai/prompts/steering.js

@@ -55,5 +55,5 @@ function formatExampleValue(value) {
     if (isString(value)) {
         return value;
     }
-    return JSON.stringify(value);
+    return JSON.stringify(value, null, 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.191",
+  "version": "0.93.193",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"