@tstdl/base 0.93.192 → 0.93.194

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

@@ -16,6 +16,8 @@ export declare class PromptBuilder {
     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;
+    enableSystemOutputRules(enabled?: boolean): this;
+    enableOutputRules(enabled?: boolean): 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

@@ -14,8 +14,10 @@ export class PromptBuilder {
     #task;
     #systemOutputSchema;
     #systemOutputExamples;
+    #systemOutputRules = false;
     #outputSchema;
     #outputExamples;
+    #outputRules = false;
     #systemInstructions = {};
     #instructions = {};
     #systemContextParts = {};
@@ -57,6 +59,14 @@ export class PromptBuilder {
         this.#outputExamples = examples;
         return this;
     }
+    enableSystemOutputRules(enabled = true) {
+        this.#systemOutputRules = enabled;
+        return this;
+    }
+    enableOutputRules(enabled = true) {
+        this.#outputRules = enabled;
+        return this;
+    }
     setSystemInstructionsOverride(override) {
         this.#systemInstructionsOverride = override;
         return this;
@@ -108,6 +118,7 @@ export class PromptBuilder {
             instructions: this.#systemInstructions,
             outputSchema: this.#systemOutputSchema,
             outputExamples: this.#systemOutputExamples,
+            outputRules: this.#systemOutputRules,
             task: this.#systemTask,
             media: this.#systemMedia,
             language: this.#language,
@@ -121,6 +132,7 @@ export class PromptBuilder {
             instructions: this.#instructions,
             outputSchema: this.#outputSchema,
             outputExamples: this.#outputExamples,
+            outputRules: this.#outputRules,
             task: this.#task,
             media: this.#media,
             language: this.#language,
@@ -151,15 +163,20 @@ 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\`\`\``;
-        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".',
-            'Optional fields with missing data': 'Omit the key entirely (sparse JSON).',
-        });
+    const hasOutputSchema = isDefined(data.outputSchema);
+    if (hasOutputSchema || data.outputRules || isDefined(data.outputExamples)) {
+        if (hasOutputSchema) {
+            const schema = convertToOpenApiSchema(data.outputSchema);
+            const schemaJson = JSON.stringify(schema, null, 2);
+            instructions['**Output Schema**'] = `\`\`\`json\n${schemaJson}\n\`\`\``;
+        }
+        if (data.outputRules) {
+            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".',
+                'Optional fields with missing data': 'Omit the key entirely (sparse JSON).',
+            });
+        }
         if (isDefined(data.outputExamples) && (data.outputExamples.length > 0)) {
             instructions['**Output Examples**'] = fewShotPrompt(data.outputExamples);
         }

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/document-management/server/services/document-management-ai.prompts.d.ts

@@ -16,7 +16,7 @@ export declare const dataExtractionFields: {
     Tags: string;
     Date: string;
 };
-export declare function createDataExtractionPrompt(schema: SchemaTestable): PromptBuilder;
+export declare function createDataExtractionPrompt(): PromptBuilder;
 export declare const assignCollectionSchema: import("../../../schema/index.js").ObjectSchema<{
     collectionIds: string[];
 }>;

package/document-management/server/services/document-management-ai.prompts.js

@@ -8,7 +8,7 @@ export function createContentExtractionPrompt() {
     return promptBuilder()
         .setSystemRole(DOCUMENT_MANAGEMENT_SYSTEM_ROLE)
         .setTask('Transcribe the attached document into Markdown following the instructions.')
-        .setOutputSchema(contentExtractionSchema)
+        .enableOutputRules()
         .addInstructions({
         'Objective': 'Convert the provided document into semantically structured, clean Markdown.',
         'Critical Constraints': orderedList([
@@ -56,12 +56,11 @@ export function createClassifySchema(validTypes) {
     return object({ documentType: enumeration(validTypes) });
 }
 export function createClassifyPrompt(validTypes) {
-    const schema = createClassifySchema(validTypes);
     return promptBuilder()
         .setSystemRole(DOCUMENT_MANAGEMENT_SYSTEM_ROLE)
         .setRole('Document Taxonomy Specialist')
         .setTask('Determine the single most accurate document type from the provided list based on the document.')
-        .setOutputSchema(schema, CLASSIFY_FEW_SHOT)
+        .setOutputExamples(CLASSIFY_FEW_SHOT)
         .addInstructions({
         'Analysis Strategy': orderedList([
             'Scan the header and title for explicit document type names (e.g., "Invoice", "Contract", "Bill of Lading").',
@@ -85,12 +84,12 @@ export const dataExtractionFields = {
     Tags: 'Generate 3-5 keywords for categorization. Only use important information missing in title, subtitle and properties. Prioritize reusing of existing tags where possible.',
     Date: 'Identify the *creation* date of the document. If multiple dates exist, prioritize the primary date (like invoice or letter Date). Return as object with year, month and day.',
 };
-export function createDataExtractionPrompt(schema) {
+export function createDataExtractionPrompt() {
     return promptBuilder()
         .setSystemRole(DOCUMENT_MANAGEMENT_SYSTEM_ROLE)
         .setRole('Structured Data Extraction Analyst')
         .setTask('Analyze the document and extract metadata and specific properties defined in the output schema following the instructions.')
-        .setOutputSchema(schema)
+        .enableOutputRules()
         .addInstructions({
         'Field Specific Instructions': dataExtractionFields,
         'Property Extraction': orderedList([
@@ -119,7 +118,7 @@ export function createAssignCollectionPrompt() {
         .setSystemRole(DOCUMENT_MANAGEMENT_SYSTEM_ROLE)
         .setRole('Digital Filing Assistant')
         .setTask('Select the most appropriate collections for this document from the provided list following the instructions.')
-        .setOutputSchema(assignCollectionSchema, ASSIGN_COLLECTION_FEW_SHOT)
+        .setOutputExamples(ASSIGN_COLLECTION_FEW_SHOT)
         .addInstructions({
         'Matching Logic': orderedList([
             'Direct Key-Match: Look for exact keyword matches between the collection name and the document metadata.',
@@ -146,7 +145,7 @@ export function createAssignRequestPrompt() {
         .setSystemRole(DOCUMENT_MANAGEMENT_SYSTEM_ROLE)
         .setRole('Workflow Routing Agent')
         .setTask('Evaluate the document against the list of open requests and find the best match following the instructions.')
-        .setOutputSchema(assignRequestSchema, ASSIGN_REQUEST_FEW_SHOT)
+        .setOutputExamples(ASSIGN_REQUEST_FEW_SHOT)
         .addInstructions({
         'Matching Rules': orderedList({
             'Hard Constraints': 'If a Request has a "Comment" or specific property requirement, the document MUST fulfill it strictly (e.g., "Need bill from July" must match date).',

package/document-management/server/services/document-management-ai.service.js

@@ -134,7 +134,7 @@ let DocumentManagementAiService = DocumentManagementAiService_1 = class Document
             const override = (isNotNull(property.key) ? aiConfig.extraction?.properties?.[property.key] : undefined) ?? aiConfig.extraction?.properties?.[property.label];
             return isDefined(override) ? mergeInstructions(`Extract value for property "${property.label}".`, [override]) : undefined;
         }).filter(isDefined);
-        const promptBuilder = createDataExtractionPrompt(generationSchema);
+        const promptBuilder = createDataExtractionPrompt();
         promptBuilder.addInstructions({
             'Field Specific Instructions': mergedFieldInstructions,
             'Additional Property Extraction': isDefined(mergedPropertyInstructions) && (mergedPropertyInstructions.length > 0)

package/document-management/server/validators/ai-validation-executor.js

@@ -26,7 +26,7 @@ export class AiValidationExecutor extends DocumentValidationExecutor {
             .setSystemTask('Validate a document based on the provided validation instructions and document content.')
             .setTask('Validate the document based on the provided system and validation instructions and the document content.')
             .addInstructions({ 'Validation Instructions': validationInstructions })
-            .setOutputSchema(this.schema)
+            .enableOutputRules()
             .addMedia(documentContent, context.document.mimeType);
         if (isDefined(language)) {
             builder.setLanguage(language);

package/package.json

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