@tstdl/base 0.93.132 → 0.93.134

package/ai/prompts/index.d.ts

@@ -2,4 +2,5 @@ export * from './build.js';
 export * from './format.js';
 export * from './instructions-formatter.js';
 export * from './instructions.js';
+export * from './prompt-builder.js';
 export * from './steering.js';

package/ai/prompts/index.js

@@ -2,4 +2,5 @@ export * from './build.js';
 export * from './format.js';
 export * from './instructions-formatter.js';
 export * from './instructions.js';
+export * from './prompt-builder.js';
 export * from './steering.js';

package/ai/prompts/instructions-formatter.js

@@ -35,6 +35,34 @@ function getPrefix(style, index, sectionDepth) {
             return '';
     }
 }
+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) {
+        lines.shift();
+    }
+    // Remove trailing empty line if any
+    if (lines.length > 0 && lines[lines.length - 1].trim().length == 0) {
+        lines.pop();
+    }
+    if (lines.length == 0) {
+        return '';
+    }
+    // Find minimum indentation (excluding empty lines)
+    const minIndent = lines
+        .filter((line) => line.trim().length > 0)
+        .reduce((min, line) => {
+        const match = /^\s*/.exec(line);
+        return Math.min(min, match ? match[0].length : 0);
+    }, Infinity);
+    if (minIndent == Infinity) {
+        return lines.join('\n').trim();
+    }
+    return lines.map((line) => line.slice(minIndent)).join('\n').trim();
+}
 /**
  * Formats a string that might span multiple lines.
  * It calculates the hanging indent based on the length of the prefix used on the first line.
@@ -63,7 +91,7 @@ function processNode(node, context) {
     if (isString(node)) {
         const isSection = context.style == 'sections';
         const currentBaseIndent = ' '.repeat(isSection ? 0 : context.indentDepth * INDENT_SIZE);
-        return formatWithHangingIndent(node, currentBaseIndent, '');
+        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.
@@ -72,7 +100,7 @@ function processNode(node, context) {
         // 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 ? `${node.instruction.trim()}\n\n` : '';
+        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
@@ -90,7 +118,7 @@ function processNode(node, context) {
         return node.map((item, index) => {
             const prefix = getPrefix(context.style, index, context.sectionDepth);
             if (isString(item)) {
-                return formatWithHangingIndent(item, currentBaseIndent, prefix);
+                return formatWithHangingIndent(dedent(item), currentBaseIndent, prefix);
             }
             return processNode(item, context);
         }).join(separator);
@@ -102,7 +130,7 @@ function processNode(node, context) {
         // 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)) ? ` ${value.instruction}` : '';
+        const instruction = (isValueWrapper && isDefined(value.instruction)) ? ` ${dedent(value.instruction)}` : '';
         const childStyle = isValueWrapper ? value.style : (isSection ? 'unordered' : 'unordered');
         // Formatting the Header Line (The Key)
         let headerLine = '';
@@ -132,14 +160,14 @@ function processNode(node, context) {
             // or a new paragraph for Sections.
             if (isSection) {
                 // Section: Header \n\n Content
-                return `${headerLine}\n\n${effectiveValue.trim()}`;
+                return `${headerLine}\n\n${dedent(effectiveValue)}`;
             }
             else {
                 // 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} ${effectiveValue}`.trim();
+                const fullLine = `${headerLine} ${dedent(effectiveValue)}`.trim();
                 return formatWithHangingIndent(fullLine, currentBaseIndent, '');
             }
         }

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

@@ -0,0 +1,24 @@
+import type { Part } from 'genkit';
+import type { ObjectLiteral } from '../../types/index.js';
+import { type Instructions } from './instructions-formatter.js';
+export type PromptBuilderInstructions = Record<string, Instructions>;
+export type PromptBuilderContext = Record<string, PromptBuilderContextItem>;
+export type PromptBuilderContextItem = ObjectLiteral;
+export declare class PromptBuilder {
+    #private;
+    setSystemRole(role: string): this;
+    setRole(role: string): this;
+    setSystemTask(task: string): this;
+    setTask(task: string): this;
+    addSystemMedia(content: Uint8Array, mimeType: string): this;
+    addMedia(content: Uint8Array, mimeType: string): this;
+    addSystemInstructions(instructions: Record<string, Instructions>): this;
+    addInstructions(instructions: Record<string, Instructions>): this;
+    addSystemContext(title: string, context: PromptBuilderContextItem): this;
+    addSystemContext(context: PromptBuilderContext): this;
+    addContext(title: string, context: PromptBuilderContextItem): this;
+    addContext(context: PromptBuilderContext): this;
+    buildSystemPrompt(): Part[];
+    buildUserPrompt(): Part[];
+}
+export declare function promptBuilder(): PromptBuilder;

package/ai/prompts/prompt-builder.js

@@ -0,0 +1,115 @@
+import { encodeBase64 } from '../../utils/base64.js';
+import { fromEntries, objectEntries, objectKeys } from '../../utils/object/index.js';
+import { assertObjectPass, isDefined, isString } from '../../utils/type-guards.js';
+import { formatData } from './format.js';
+import { formatInstructions, sections } from './instructions-formatter.js';
+export class PromptBuilder {
+    #systemRole;
+    #role;
+    #systemTask;
+    #task;
+    #systemInstructions = {};
+    #instructions = {};
+    #systemContextParts = {};
+    #contextParts = {};
+    #systemMedia = [];
+    #media = [];
+    setSystemRole(role) {
+        this.#systemRole = role;
+        return this;
+    }
+    setRole(role) {
+        this.#role = role;
+        return this;
+    }
+    setSystemTask(task) {
+        this.#systemTask = task;
+        return this;
+    }
+    setTask(task) {
+        this.#task = task;
+        return this;
+    }
+    addSystemMedia(content, mimeType) {
+        addMedia(content, mimeType, this.#systemMedia);
+        return this;
+    }
+    addMedia(content, mimeType) {
+        addMedia(content, mimeType, this.#media);
+        return this;
+    }
+    addSystemInstructions(instructions) {
+        this.#systemInstructions = { ...this.#systemInstructions, ...instructions };
+        return this;
+    }
+    addInstructions(instructions) {
+        this.#instructions = { ...this.#instructions, ...instructions };
+        return this;
+    }
+    addSystemContext(titleOrContext, contextOrNothing) {
+        if ((arguments.length == 1)) {
+            this.#systemContextParts = { ...this.#systemContextParts, ...assertObjectPass(titleOrContext) };
+            return this;
+        }
+        this.#systemContextParts[titleOrContext] = contextOrNothing;
+        return this;
+    }
+    addContext(titleOrContext, contextOrNothing) {
+        if ((arguments.length == 1)) {
+            this.#contextParts = { ...this.#contextParts, ...assertObjectPass(titleOrContext) };
+            return this;
+        }
+        this.#contextParts[titleOrContext] = contextOrNothing;
+        return this;
+    }
+    buildSystemPrompt() {
+        return buildPrompt({
+            role: this.#systemRole,
+            context: this.#systemContextParts,
+            instructions: this.#systemInstructions,
+            task: this.#systemTask,
+            media: this.#systemMedia,
+        });
+    }
+    buildUserPrompt() {
+        return buildPrompt({
+            role: this.#role,
+            context: this.#contextParts,
+            instructions: this.#instructions,
+            task: this.#task,
+            media: this.#media,
+        });
+    }
+}
+export function promptBuilder() {
+    return new PromptBuilder();
+}
+function addMedia(content, mimeType, targetArray) {
+    const base64Data = encodeBase64(content);
+    const dataUrl = `data:${mimeType};base64,${base64Data}`;
+    targetArray.push({ media: { url: dataUrl } });
+}
+function buildPrompt(data) {
+    const instructions = {};
+    if (isDefined(data.role)) {
+        instructions['**Role**'] = data.role;
+    }
+    if (isDefined(data.context) && objectKeys(data.context).length > 0) {
+        const contextEntries = objectEntries(data.context).map(([key, contextPart]) => {
+            const string = isString(contextPart) ? contextPart : `\`\`\`toon\n${formatData(contextPart)}\n\`\`\``;
+            return [key, string];
+        });
+        instructions['**Context**'] = sections(fromEntries(contextEntries));
+    }
+    if (isDefined(data.instructions) && (objectKeys(data.instructions).length > 0)) {
+        instructions['**Instructions**'] = data.instructions;
+    }
+    if (isDefined(data.task)) {
+        instructions['**Task**'] = data.task;
+    }
+    const formattedInstructions = formatInstructions(instructions);
+    return [
+        ...(data.media ?? []),
+        { text: formattedInstructions },
+    ];
+}

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

@@ -0,0 +1 @@
+import '../../polyfills.js';

package/examples/ai/prompt-builder.js

@@ -0,0 +1,107 @@
+import '../../polyfills.js';
+import { orderedList, promptBuilder, unorderedList } from '../../ai/index.js';
+import { Application } from '../../application/application.js';
+import { provideModule, provideSignalHandler } from '../../application/index.js';
+import { PrettyPrintLogFormatter } from '../../logger/index.js';
+import { provideConsoleLogTransport } from '../../logger/transports/console.js';
+async function main() {
+    const builder = promptBuilder();
+    // 1. Configure System Instructions
+    // System instructions define the persona and fundamental rules of the AI.
+    builder
+        .setSystemRole('A world-class senior software architect and mentor.')
+        .setSystemTask('Review the provided code for architectural flaws, performance bottlenecks, and security vulnerabilities.')
+        .addSystemContext('Project Architecture', {
+        type: 'Monorepo',
+        language: 'TypeScript',
+        framework: 'tstdl (Custom Framework)',
+        modules: ['API', 'ORM', 'Injector', 'Logger'],
+    })
+        .addSystemContext('Environment', {
+        nodeVersion: process.version,
+        platform: process.platform,
+        memoryLimit: '4GB',
+    })
+        .addSystemInstructions({
+        'Output Style': unorderedList('Ensure the output follows these structural rules:', {
+            Language: 'Always respond in English.',
+            Tone: 'Professional, concise, and constructive.',
+            Format: orderedList('Structure your response as follows:', [
+                'Executive Summary',
+                'Detailed Findings (categorized by severity)',
+                'Code Improvements (with examples)',
+                'Next Steps',
+            ]),
+        }),
+        'Formatting rules': orderedList('Follow these rules for code formatting:', {
+            Indentation: 'Use 2 spaces.',
+            Semicolons: 'Always use semicolons.',
+            Quotes: 'Use single quotes.',
+        }),
+        'Response Constraints': unorderedList('Must never include:', [
+            'Personal opinions.',
+            'Speculative performance metrics without data.',
+            'Unnecessary apologies.',
+        ]),
+        'Safety Guidelines': unorderedList([
+            'Never suggest disabling security features.',
+            'Avoid recommending deprecated libraries.',
+            'Always prioritize type safety.',
+        ]),
+    });
+    // 2. Configure User Prompt
+    // The prompt defines the specific request and context for the current interaction.
+    builder
+        .setRole('A developer seeking feedback on a new feature.')
+        .setTask('Please review this new User Service implementation.')
+        .addContext('Code to Review', `
+      @Singleton()
+      export class UserService extends getRepository(User) {
+        readonly #logger = inject(Logger, UserService.name);
+
+        async createUser(data: UserData): Promise<User> {
+          this.#logger.info('Creating user', { data });
+          return this.insert(data);
+        }
+      }
+    `)
+        .addContext('Requirements', [
+        'Must use private class fields (#).',
+        'Must use the project logger.',
+        'Must extend the base repository.',
+    ])
+        .addContext('Free Text User Hint', 'Focus on potential issues with dependency injection and logging practices.')
+        .addInstructions({
+        'Specific Focus': 'Pay special attention to the use of dependency injection and logging.',
+    });
+    // 3. Add Media (Simulated)
+    // Media can be added (e.g., screenshots of logs or diagrams).
+    const dummyImage = new Uint8Array([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+    builder.addMedia(dummyImage, 'image/png');
+    // 4. Build and Display
+    const systemMessage = builder.buildSystemPrompt();
+    const userMessage = builder.buildUserPrompt();
+    console.log('--- SYSTEM MESSAGE ---');
+    for (const part of systemMessage) {
+        if (part.text) {
+            console.log(part.text);
+        }
+        if (part.media) {
+            console.log(`[Media: ${part.media.url}]`);
+        }
+    }
+    console.log('\n\n--- USER PROMPT ---');
+    for (const part of userMessage) {
+        if (part.text) {
+            console.log(part.text);
+        }
+        if (part.media) {
+            console.log(`[Media: ${part.media.url}]`);
+        }
+    }
+}
+Application.run('PromptBuilder Demo', [
+    provideConsoleLogTransport(PrettyPrintLogFormatter),
+    provideModule(main),
+    provideSignalHandler(),
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.132",
+  "version": "0.93.134",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -162,8 +162,8 @@
     "file-type": "^21.3",
     "genkit": "^1.28",
     "handlebars": "^4.7",
-    "@aws-sdk/client-s3": "^3.991",
-    "@aws-sdk/s3-request-presigner": "^3.991",
+    "@aws-sdk/client-s3": "^3.992",
+    "@aws-sdk/s3-request-presigner": "^3.992",
     "mjml": "^4.18",
     "nodemailer": "^8.0",
     "pg": "^8.18",

package/test5.js

@@ -1,11 +1,14 @@
 import './polyfills.js';
+import { promptBuilder } from './ai/index.js';
 import { Application } from './application/application.js';
 import { provideModule, provideSignalHandler } from './application/index.js';
 import { PrettyPrintLogFormatter } from './logger/index.js';
 import { provideConsoleLogTransport } from './logger/transports/console.js';
-import { mergePdfs } from './pdf/utils.js';
 async function main(_cancellationSignal) {
-    await mergePdfs(['asd', 'bsa']);
+    const x = promptBuilder();
+    console.log(x.buildSystemPrompt()[0].text);
+    console.log('\n\n---\n\n');
+    console.log(x.buildUserPrompt()[0].text);
 }
 Application.run('Test', [
     provideConsoleLogTransport(PrettyPrintLogFormatter),